Skip to content

Commit 65f701b

Browse files
migmartrimigmartri
authored
docs: update readme and main diagram (#1772)
Signed-off-by: Miguel Martinez <miguel@chainloop.dev>
1 parent afcb8af commit 65f701b

File tree

2 files changed

+69
-70
lines changed

2 files changed

+69
-70
lines changed

‎README.md

Lines changed: 69 additions & 70 deletions
Original file line numberDiff line numberDiff line change
@@ -11,74 +11,10 @@
1111
1212
## What is it?
1313

14-
Chainloop is an open-source Software Supply Chain control plane, a single source of truth for metadata and artifacts, plus a declarative attestation process.
15-
16-
With Chainloop, SecOps teams can declaratively state the pieces of evidence and artifact expectations for their organization’s CI/CD workflows. At the same time, they can rest assured that the metadata will reach the desired destination for storage and analysis, always meeting the latest standards and best practices.
17-
18-
On the other hand, developer teams do not need to become security experts. The attestation crafting tool will guide them with guardrails and a familiar developer experience.
14+
[Chainloop](https://github.com/chainloop-dev/chainloop) is an open-source evidence store for your Software Supply Chain attestations, Software Bill of Materials (SBOMs), VEX, SARIF, QA reports, and more. With Chainloop, Security, Compliance, and Risk management teams can define security and compliance policies, what evidence and artifacts they want to receive, and where to store them. On the other hand, developers are shielded from all this complexity by being given simple instructions on what to provide when instrumenting their CI/CD pipelines.
1915

2016
To learn more about the project motivation please look at [our documentation](https://docs.chainloop.dev) and see it in action in [this video](https://www.youtube.com/watch?v=GfSR2ZkZ3as).
2117

22-
## Getting started
23-
24-
See the [getting started guide](https://docs.chainloop.dev/getting-started/installation#command-line-interface-cli-installation) for detailed information on a) how to download and configure the Chainloop CLI and b) how to deploy Chainloop on your Kubernetes Cluster.
25-
26-
### Command Line Interface (CLI) installation
27-
28-
> Alternatively, you can download the CLI from the [releases pages](https://github.com/chainloop-dev/chainloop/releases) or [build it from source](./CONTRIBUTING.md).
29-
30-
To **install the latest version** for macOS, Linux or Windows (using [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)) just choose one of the following installation methods.
31-
32-
```bash
33-
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s
34-
```
35-
36-
you can retrieve a specific version with
37-
38-
```bash
39-
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --version v0.8.95
40-
```
41-
42-
and customize the install path (default to /usr/local/bin)
43-
44-
```bash
45-
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --path /my-path
46-
```
47-
48-
if [`cosign`](https://docs.sigstore.dev/cosign) is present in your system, in addition to the checksum check, a signature verification will be performed. This behavior can be enforced via the `--force-verification` flag.
49-
50-
```bash
51-
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --force-verification
52-
```
53-
54-
### Deploy Chainloop (optional)
55-
56-
Downloading the CLI is everything you need to give Chainloop a try, since, by default, it points to a [running instance of Chainloop](https://app.chainloop.dev).
57-
58-
You can also **run your own Chainloop instance** on your Kubernetes cluster by leveraging [this Helm Chart](./deployment/chainloop/).
59-
60-
### Configure CLI (optional)
61-
62-
If you are running your [own instance](https://github.com/chainloop-dev/chainloop) of the Control Plane. You can make the CLI point to your instance by using the `chainloop config save` command.
63-
64-
```sh
65-
chainloop config save \
66-
--control-plane my-controlplane.acme.com \
67-
--artifact-cas cas.acme.com
68-
```
69-
70-
### Authentication
71-
72-
Authenticate to the Control Plane by running
73-
74-
```bash
75-
$ chainloop auth login
76-
```
77-
78-
### Finishing the setup
79-
80-
Once you've been logged in, follow [these instructions](https://docs.chainloop.dev/getting-started/setup) to learn how to set up your account.
81-
8218
## How does it work?
8319

8420
### Compliant Single Source of Truth
@@ -95,27 +31,32 @@ Chainloop also makes sure the crafting of artifacts and attestation follows **be
9531

9632
One key aspect is that in Chainloop, CI/CD integrations are declared via [**Workflow Contracts**](https://docs.chainloop.dev/getting-started/workflow-definition#workflow-contracts).
9733

98-
A [Workflow Contract](https://docs.chainloop.dev/reference/operator/contract) gives operators **full control over what kind of data (build info, materials) must be received as part of the attestation and the environment where these workflows must be executed at**. This enables an easy, and maintainable, way of propagating and enforcing requirements downstream to your organization.
34+
A [Workflow Contract](https://docs.chainloop.dev/reference/operator/contract) gives Compliance and Security teams **full control over what kind of data (build info, materials) must be received as part of the attestation and the environment where these workflows must be executed at**. This enables an easy, and maintainable, way of propagating and enforcing requirements downstream to your organization.
9935

100-
You can think of it as an [**API for your organization's Software Supply Chain**](https://docs.chainloop.dev/reference/operator/contract) that both parties, development and SecOps teams can use to interact effectively.
36+
You can think of it as an [**API for your organization's Software Supply Chain**](https://docs.chainloop.dev/reference/operator/contract) that both parties, development and Compliance and Security teams can use to interact effectively.
10137

10238
![Chainloop Contracts](./docs/img/overview-3.png)
10339

40+
### Policy as code
41+
42+
Compliance and Security teams can [craft](https://docs.chainloop.dev/guides/rego-policies/) [Rego](https://www.openpolicyagent.org/docs/latest/policy-language/) policies, and [attach](https://docs.chainloop.dev/reference/policies) them to workflow contracts. Those policies will be automatically evaluated, and their results will be added to the attestation before signing and storage.
43+
44+
10445
### We meet you where you are with third-party integrations
10546

10647
Operators can set up third-party integrations such as [Dependency-Track](https://docs.chainloop.dev/guides/dependency-track), or [Guac](https://docs.chainloop.dev/guides/guac/) for SBOM analysis or a storage backend such as an OCI registry, or cloud blob storage to place the received artifacts, pieces of evidence and attestation metadata.
10748

10849
![Chainloop Overview](./docs/img/overview-2.png)
10950

110-
Ops can mix and match with different integrations while **not requiring developers to make any changes on their side**!
51+
Compliance and Security teams can mix and match with different integrations while **not requiring developers to make any changes on their side**!
11152

11253
To learn more and to find the list of available integrations, check our [integrations page](./devel/integrations.md).
11354

11455
### Role-tailored experience
11556

116-
Chainloop makes sure to clearly define the responsibilities, experience and functional scope of the **two main personas, Security/Operation (SecOps) and Development/Application teams**.
57+
Chainloop makes sure to clearly define the responsibilities, experience and functional scope of the **two main personas, Compliance/Security and Development teams**.
11758

118-
SecOps are the ones in charge of defining the Workflow Contracts, setting up third-party integrations, or having access to the control plane where all the Software Supply Chain Security bells and whistles are exposed.
59+
Compliance and Security teams are the ones in charge of defining the Workflow Contracts, crafting policies, setting up third-party integrations, or having access to the control plane where all the Software Supply Chain Security bells and whistles are exposed.
11960

12061
Development teams on the other hand, just need to integrate Chainloop's jargon-free [crafting tool](https://docs.chainloop.dev/getting-started/attestation-crafting) and follow the steps via a familiar DevExp to make sure they comply with the Workflow Contract defined by the SecOps team. No need to learn in-toto, signing, SLSA, OCI, APIs, nada :)
12162

@@ -146,7 +87,65 @@ Chainloop supports the collection of the following list of evidence types. For t
14687
- Custom Evidence Type: Custom piece of evidence that doesn't fit in any other category, for instance, an approval report in json format, etc.
14788
- Key-Value metadata pairs
14889

90+
## Getting started
91+
92+
See the [getting started guide](https://docs.chainloop.dev/getting-started/installation#command-line-interface-cli-installation) for detailed information on a) how to download and configure the Chainloop CLI and b) how to deploy Chainloop on your Kubernetes Cluster.
93+
94+
### Command Line Interface (CLI) installation
95+
96+
> Alternatively, you can download the CLI from the [releases pages](https://github.com/chainloop-dev/chainloop/releases) or [build it from source](./CONTRIBUTING.md).
97+
98+
To **install the latest version** for macOS, Linux or Windows (using [WSL](https://learn.microsoft.com/en-us/windows/wsl/install)) just choose one of the following installation methods.
99+
100+
```bash
101+
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s
102+
```
149103

104+
you can retrieve a specific version with
105+
106+
```bash
107+
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --version v0.8.95
108+
```
109+
110+
and customize the install path (default to /usr/local/bin)
111+
112+
```bash
113+
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --path /my-path
114+
```
115+
116+
if [`cosign`](https://docs.sigstore.dev/cosign) is present in your system, in addition to the checksum check, a signature verification will be performed. This behavior can be enforced via the `--force-verification` flag.
117+
118+
```bash
119+
curl -sfL https://raw.githubusercontent.com/chainloop-dev/chainloop/main/docs/static/install.sh | bash -s -- --force-verification
120+
```
121+
122+
### Deploy Chainloop (optional)
123+
124+
Downloading the CLI is everything you need to give Chainloop a try, since, by default, it points to a [running instance of Chainloop](https://app.chainloop.dev).
125+
126+
You can also **run your own Chainloop instance** on your Kubernetes cluster by leveraging [this Helm Chart](./deployment/chainloop/).
127+
128+
### Configure CLI (optional)
129+
130+
If you are running your [own instance](https://github.com/chainloop-dev/chainloop) of the Control Plane. You can make the CLI point to your instance by using the `chainloop config save` command.
131+
132+
```sh
133+
chainloop config save \
134+
--control-plane my-controlplane.acme.com \
135+
--artifact-cas cas.acme.com
136+
```
137+
138+
### Authentication
139+
140+
Authenticate to the Control Plane by running
141+
142+
```bash
143+
$ chainloop auth login
144+
```
145+
146+
### Finishing the setup
147+
148+
Once you've been logged in, follow [these instructions](https://docs.chainloop.dev/getting-started/setup) to learn how to set up your account.
150149
## Documentation
151150

152151
To learn more, please visit the Chainloop project's documentation website, https://docs.chainloop.dev where you will find a getting started guide, FAQ, examples, and more.

‎docs/img/overview-2.png

-156 KB
Loading

0 commit comments

Comments
 (0)