Add initial use cases docs

Signed-off-by: Andrea Frittoli <[email protected]>

Author: afrittoli

docs/README.md

@@ -0,0 +1,48 @@
+# CDEvents Implementation
+
+The implementation of CDEvents is use case driven. We focus on a few use cases that demonstrate the business value of interoperability in the CI/CD space and for each of them we identify a target architecture, its logical building blocks and a set of software components that can be used to implement it.
+
+Some of the software required is part of the CDEvents project and other is external. All proposed implementation focus exclusively on open source software components. Commercial software that implements standard protocols like CDEvents can be slotted in to replace or complement the open source software adopted by the CDEvents Implementation WG.
+
+## Use Cases
+
+CDEvents use cases may apply to two personas: open source project communities and organizations doing in-house software development.
+The requirements and design of the implementation vary based on the persona and are documented in the use-case specific document.
+
+- [Enhance Security Posture through Automation](./security_automation.md)
+- Improve Developer Experience through Consistency and Visibility (TBD)
+- Drive Efficiency through DevOps Metrics (TBD)
+
+## Common Components
+
+### Messaging Platform
+
+TBD - Link to component requirements and design
+
+### Event Producers
+
+TBD - Describe various type of event producers: tools native, via tool plugin, via external adapter, via external watcher
+
+#### Webhook Adapter
+
+TBD - Adapter and plugins
+
+### CDEvents SDKs
+
+CDEvents provides SDKs for various programming languages.
+The Implementation WG focusses on providing consistency across the various SDKs to simplify adoption.
+
+* [Golang SDK][sdk-go]
+* [Java SDK][sdk-java]
+* [Rust SDK][sdk-rust]
+* [Python SDK][sdk-python]
+* [.NET SDK][sdk-dotnet]
+
+
+<!-- External Links -->
+
+[sdk-go]: https://github.com/cdevents/sdk-go
+[sdk-java]: https://github.com/cdevents/sdk-java
+[sdk-rust]: https://github.com/cdevents/sdk-rust
+[sdk-python]: https://github.com/cdevents/sdk-python
+[sdk-dotnet]: https://github.com/cdevents/sdk-dotnet

docs/security_automation.drawio.svg

@@ -0,0 +1,44 @@
+# Use Case: Enhance Security Posture through Automation
+
+Software development requires an ever-growing set of security practices to be implemented in order to produce software that can be trusted. Generating Software Bill of Materials (SBOMs), running vulnerability scans, static analysis, signing artifacts and more.
+
+Implementing all these in existing CI/CD pipelines introduces churn and extra cognitive load on DevOps engineers, which maintain the pipeline definitions and need to familiarize themselves with all this new technologies.
+
+It's not only about triggering extra CI jobs: this new checks and practices in turn produce extra data which needs to be stored, evaluated and understood. 
+
+CDEvents allow implementing this new security practices as a result of events in existing CI/CD pipelines. This way the implementation of security practices does not impact the original pipelines and can be performed by individuals that are familiar with the security requirements and technologies.
+Storing the events from the existing CI/CD pipelines along with those from the security tools in and *evidence store* allows for auditing of CI/CD processes and obtaining lineage information about artifacts produced in the software factory.
+
+## State of the Art
+
+Vendors like GitHub provide integrated tools, like "Dependabot" and "CodeQL" which can be used to add some of the required security features with minimal configuration. Such tools are tightly integrated with GitHub's own CI/CD system and are not easily ported to other CI/CD systems.
+
+## Requirements
+
+* Minimal or no change to existing CI/CD systems and pipelines
+* Security checks and tools can be triggered in response to **policies** applied to a **collection** of events
+* Execution of security tools can be audited
+
+## Architecture
+
+1. Existing CI/CD pipelines produce events about their lifecycle and artifacts being built. All the events are sent to the message bus. A few options are available:
+    * The CI/CD tool natively supports CDEvents
+    * A plugin is available for the tool that produces CDEvents
+    * The CI/CD tool can produce events or trigger webhooks. They can be converted to CDEvents via an adapter
+    * The CI/CD tool can be observed in some way by an external watcher which can produce CDEvents
+
+2. An event ingestor process subscribes to the message bus, consumes events and stores them in an event database.
+3. A query API allows high-performance access to previous events stored in the event database.
+4. A policy engine subscribes to specific events. It evaluates policies that apply to the specific events and previous events (accessible via the query API) and triggers the execution of security tools and pipelines in response.
+
+5. Security engineers may define policies in the policy engine to add new security tooling, without touching the original pipelines. 
+6. Security engineers and DevOps engineers may observe the execution or regular and security pipelines through a consolidated dashboard. 
+7. Security engineers may audit all events associated with specific software artifacts.
+
+![](./security_automation.drawio.svg)
+
+## Personas
+
+### Open Source Projects
+
+### In-House Development