Skip to content

Commit adc0d33

Browse files
oliverbaehlerprometherion
oliverbaehler
authored and
prometherion
committed
docs(repo): add security and contribution
Signed-off-by: Oliver Bähler <[email protected]>
1 parent af20d2e commit adc0d33

File tree

2 files changed

+200
-0
lines changed

2 files changed

+200
-0
lines changed

‎DEVELOPMENT.md

+85
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,85 @@
1+
# How to
2+
3+
## Chart Development
4+
5+
### Chart Linting
6+
7+
The chart is linted with [ct](https://github.com/helm/chart-testing). You can run the linter locally with this command:
8+
9+
```
10+
make helm-lint
11+
```
12+
13+
### Documentation
14+
15+
The documentation for each chart is done with [helm-docs](https://github.com/norwoodj/helm-docs). This way we can ensure that values are consistent with the chart documentation. Run this anytime you make changes to a `values.yaml` file:
16+
17+
```
18+
make helm-docs
19+
```
20+
21+
## Run locally for test and debug
22+
23+
This guide helps new contributors to locally debug in _out or cluster_ mode the project.
24+
25+
1. You need to run a kind cluster and find the endpoint port of `kind-control-plane` using `docker ps`:
26+
27+
```bash
28+
> docker ps
29+
CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
30+
88432e392adb kindest/node:v1.20.2 "/usr/local/bin/entr…" 32 seconds ago Up 28 seconds 127.0.0.1:64582->6443/tcp kind-control-plane
31+
```
32+
33+
2. You need to generate TLS cert keys for localhost, you can use [mkcert](https://github.com/FiloSottile/mkcert):
34+
35+
```bash
36+
> cd /tmp
37+
> mkcert localhost
38+
> ls
39+
localhost-key.pem localhost.pem
40+
```
41+
42+
3. Run the proxy with the following options
43+
44+
```bash
45+
# Set KUBECONFIG environment variable with the Kubernetes configuration file if you are not currently using it.
46+
# export KUBECONFIG=<YOUR KUBERNETES CONFIGURATION FILE> or just type it before the command, i.e. `KUBECONFIG=<YOUR KUBERNETES CONFIGURATION FILE> go run main.go ...`
47+
$ go run main.go --ssl-cert-path=/tmp/localhost.pem --ssl-key-path=/tmp/localhost-key.pem --enable-ssl=true
48+
```
49+
50+
4. Edit the `KUBECONFIG` file (you should make a copy and work on it) as follows:
51+
- Find the section of your cluster
52+
- replace the server path with `https://localhost:9001`
53+
- replace the certificate-authority-data path with the content of your rootCA.pem file. (if you use mkcert, you'll find with `cat "$(mkcert -CAROOT)/rootCA.pem"|base64|tr -d '\n'`)
54+
55+
5. Now you should be able to run kubectl using the proxy!
56+
57+
## Debug in a remote Kubernetes cluster
58+
59+
In some cases, you would need to debug the in-cluster mode and [`delve`](https://github.com/go-delve/delve) plays a big role here.
60+
61+
1. build the Docker image with `delve` issuing `make dlv-build`
62+
2. with the `clastix/capsule-proxy:dlv` produced Docker image, publish it or load it to your [KinD](https://github.com/kubernetes-sigs/kind) instance (`kind load docker-image --name capsule --nodes capsule-control-plane clastix/capsule-proxy:dlv`)
63+
3. change the Deployment image using `kubectl edit` or `kubectl set image deployment/capsule-proxy capsule-proxy=clastix/capsule-proxy:dlv`
64+
4. wait for the image rollout (`kubectl -n capsule-system rollout status deployment/capsule-proxy`)
65+
5. perform the port-forwarding with `kubectl -n capsule-system port-forward $(kubectl -n capsule-system get pods -l app.kubernetes.io/name=capsule-proxy --output name) 2345:2345`
66+
6. connect using your `delve` options
67+
68+
> _Nota Bene_: the application could be killed by the Liveness Probe since delve will wait for the debugger connection before starting it.
69+
> Feel free to edit and remove the probes to avoid this kind of issue.
70+
71+
## HTTP support
72+
73+
Capsule proxy supports `https` and `http`, although the latter is not recommended, we understand that it can be useful for some use cases (i.e. development, working behind a TLS-terminated reverse proxy and so on).
74+
75+
As the default behaviour is to work with `https`, we need to use the flag `--enable-ssl=false` if we really want to work under `http`.
76+
77+
After having **Capsule-Proxy** working under `http`, requests must provide *authentication* using an allowed Bearer Token. Example:
78+
79+
```bash
80+
$ TOKEN=<type your TOKEN>
81+
$ curl -H "Authorization: Bearer $TOKEN" http://localhost:9001/api/v1/namespaces
82+
```
83+
84+
> **NOTE**: `kubectl` will not work against a http server.
85+

‎SECURITY.md

+115
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,115 @@
1+
# Security Policy
2+
3+
The Capsule community has adopted this security disclosures and response policy to ensure we responsibly handle critical issues.
4+
5+
## Bulletins
6+
7+
For information regarding the security of this project please join our [slack channel](https://kubernetes.slack.com/archives/C03GETTJQRL).
8+
9+
10+
## Covered Repositories and Issues
11+
12+
When we say "a security vulnerability in capsule" we mean a security issue
13+
in any repository under the [projectcapsule GitHub organization](https://github.com/projectcapsule/).
14+
15+
This reporting process is intended only for security issues in the capsule
16+
project itself, and doesn't apply to applications _using_ capsule or to
17+
issues which do not affect security.
18+
19+
Don't use this process if:
20+
21+
* You have issues with your capsule installation or configuration
22+
* Your issue is not security related
23+
24+
25+
### Explicitly Not Covered: Vulnerability Scanner Reports
26+
27+
We do not accept reports which amount to copy and pasted output from a vulnerability
28+
scanning tool **unless** work has specifically been done to confirm that a vulnerability
29+
reported by the tool _actually exists_ in capsule.
30+
31+
## Reporting a Vulnerability
32+
33+
To report a security issue or vulnerability, [submit a private vulnerability report via GitHub](https://github.com/projectcapsule/capsule-proxy/security/advisories/new) to the repository maintainers with a description of the issue, the steps you took to create the issue, affected versions, and, if known, mitigations for the issue.
34+
35+
Describe the issue in English, ideally with some example configuration or code which allows the issue to be reproduced. Explain why you believe this to be a security issue in capsule-proxy, if that's not obvious. should contain the following:
36+
37+
* description of the problem
38+
* precise and detailed steps (include screenshots)
39+
* the affected version(s). This may also include environment relevant versions.
40+
* any possible mitigations
41+
42+
If the issue is confirmed as a vulnerability, we will open a Security Advisory and acknowledge your contributions as part of it.
43+
44+
## Reponse
45+
46+
Response times could be affected by weekends, holidays, breaks or time zone differences. That said, the security response team will endeavour to reply as soon as possible, ideally within 5 working days.
47+
48+
## Security Contacts
49+
50+
[Maintainers](./github/maintainers.yaml) of this project are responsible for the security of the project as outlined in this policy.
51+
52+
# Release Artifacts
53+
54+
[See all the available artifacts](https://github.com/orgs/projectcapsule/packages?repo_name=capsule-proxy)
55+
56+
## Verifing
57+
58+
To verify artifacts you need to have [cosign installed](https://github.com/sigstore/cosign#installation). This guide assumes you are using v2.x of cosign. All of the signatures are created using [keyless signing](https://docs.sigstore.dev/verifying/verify/#keyless-verification-using-openid-connect). We have a seperate repository for all the signatures for all the artifacts released under the projectcapsule - `ghcr.io/projectcapsule/signatures`. You can set the environment variable `COSIGN_REPOSITORY` to point to this repository. For example:
59+
60+
export COSIGN_REPOSITORY=ghcr.io/projectcapsule/signatures
61+
62+
To verify the signature of the docker image, run the following command. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule-proxy/pkgs/container/capsule-proxy):
63+
64+
COSIGN_REPOSITORY=ghcr.io/projectcapsule/signatures cosign verify ghcr.io/projectcapsule/capsule-proxy:<release_tag> \
65+
--certificate-identity-regexp="https://github.com/projectcapsule/capsule-proxy/.github/workflows/docker-publish.yml@refs/tags/*" \
66+
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" | jq
67+
68+
To verify the signature of the helm image, run the following command. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule/pkgs/container/charts%2Fcapsule):
69+
70+
COSIGN_REPOSITORY=ghcr.io/projectcapsule/signatures cosign verify ghcr.io/projectcapsule/charts/capsule-proxy:<release_tag> \
71+
--certificate-identity-regexp="https://github.com/projectcapsule/capsule-proxy/.github/workflows/helm-publish.yml@refs/tags/*" \
72+
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" | jq
73+
74+
75+
## Verifying Provenance
76+
77+
Capsule creates and attests to the provenance of its builds using the [SLSA standard](https://slsa.dev/spec/v0.2/provenance) and meets the [SLSA Level 3](https://slsa.dev/spec/v0.1/levels) specification. The attested provenance may be verified using the cosign tool.
78+
79+
Verify the provenance of the docker image. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule-proxy/pkgs/container/capsule-proxy)
80+
81+
```bash
82+
cosign verify-attestation --type slsaprovenance \
83+
--certificate-identity-regexp="https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/*" \
84+
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
85+
ghcr.io/projectcapsule/capsule-proxy:<release_tag> | jq .payload -r | base64 --decode | jq
86+
```
87+
88+
Verify the provenance of the helm image. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule-proxy/pkgs/container/charts%2Fcapsule-proxy)
89+
90+
```bash
91+
cosign verify-attestation --type slsaprovenance \
92+
--certificate-identity-regexp="https://github.com/slsa-framework/slsa-github-generator/.github/workflows/generator_container_slsa3.yml@refs/tags/*" \
93+
--certificate-oidc-issuer="https://token.actions.githubusercontent.com" \
94+
ghcr.io/projectcapsule/charts/capsule-proxy:<release_tag> | jq .payload -r | base64 --decode | jq
95+
```
96+
97+
## Software Bill of Materials (SBOM)
98+
99+
An SBOM (Software Bill of Materials) in CycloneDX JSON format is published for each Kyverno release, including pre-releases. Like signatures, SBOMs are stored in a separate repository at `ghcr.io/projectcapsule/sbom`. You can set the environment variable `COSIGN_REPOSITORY` to point to this repository. For example:
100+
101+
export COSIGN_REPOSITORY=ghcr.io/projectcapsule/sbom
102+
103+
To inspect the SBOM of the docker image, run the following command. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule-proxy/pkgs/container/capsule-proxy):
104+
105+
106+
COSIGN_REPOSITORY=ghcr.io/projectcapsule/sbom cosign download sbom ghcr.io/projectcapsule/capsule-proxy:<release_tag>
107+
108+
To inspect the SBOM of the helm image, run the following command. Replace `<release_tag>` with an [available release tag](https://github.com/projectcapsule/capsule-proxy/pkgs/container/charts%2Fcapsule-proxy):
109+
110+
COSIGN_REPOSITORY=ghcr.io/projectcapsule/sbom cosign download sbom ghcr.io/projectcapsule/charts/capsule-proxy:<release_tag>
111+
112+
113+
# Credits
114+
115+
Our Security Policy and Workflows are based on the work of the [Kyverno](https://github.com/kyverno) and [Cert-Manager](https://github.com/cert-manager) community.

0 commit comments

Comments
 (0)