From 89f0c557955636fb79f28589cc645d148a5cd6cb Mon Sep 17 00:00:00 2001 From: Kevin Amado Date: Fri, 9 Sep 2022 11:19:43 -0600 Subject: [PATCH] feat(back): #901 add slsa docs - Add slsa docs using mdbook - Deploy using github actions --- .github/workflows/prod.yml | 22 +++++ .gitlab-ci.yaml | 2 + docs/.gitignore | 1 + docs/book.toml | 18 +++++ docs/src/README.md | 3 + docs/src/SUMMARY.md | 7 ++ docs/src/security/slsa.md | 125 +++++++++++++++++++++++++++++ makes.nix | 5 +- makes/docs/builder.sh | 1 + makes/docs/main.nix | 12 +++ makes/tests/makeTemplate/test.yaml | 1 + 11 files changed, 196 insertions(+), 1 deletion(-) create mode 100644 docs/.gitignore create mode 100644 docs/book.toml create mode 100644 docs/src/README.md create mode 100644 docs/src/SUMMARY.md create mode 100644 docs/src/security/slsa.md create mode 100644 makes/docs/builder.sh create mode 100644 makes/docs/main.nix diff --git a/.github/workflows/prod.yml b/.github/workflows/prod.yml index 83027eae..6086a120 100644 --- a/.github/workflows/prod.yml +++ b/.github/workflows/prod.yml @@ -119,6 +119,28 @@ jobs: env: CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }} + linux_docs: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@2541b1294d2704b0964813337f33b291d3f8596b + - uses: docker://docker.io/nixos/nix@sha256:1d13ae379fb8caf3f859c5ce7ec6002643d60cf8b7b6147b949cc34880c93bac + name: /docs + with: + set-safe-directory: /github/workspace + args: sh -c "nix-env -if . && m . /docs" + env: + CACHIX_AUTH_TOKEN: ${{ secrets.CACHIX_AUTH_TOKEN }} + - name: deploy + uses: peaceiris/actions-gh-pages@v3 + with: + force_orphan: true + full_commit_message: ${{ github.event.head_commit.message }} + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_branch: docs + publish_dir: ~/.makes/out-docs/ + user_name: github-actions[bot] + user_email: github-actions[bot]@users.noreply.github.com + linux_envVars_example: runs-on: ubuntu-latest steps: diff --git a/.gitlab-ci.yaml b/.gitlab-ci.yaml index 02c7628b..258a6620 100644 --- a/.gitlab-ci.yaml +++ b/.gitlab-ci.yaml @@ -7,6 +7,7 @@ - m . /helloWorld '1' '2' '3' variables: GIT_DEPTH: 1 + MAKES_GIT_DEPTH: 1 /lintNix: image: ghcr.io/fluidattacks/makes:22.09 interruptible: true @@ -15,3 +16,4 @@ - m . /lintNix variables: GIT_DEPTH: 1 + MAKES_GIT_DEPTH: 1 diff --git a/docs/.gitignore b/docs/.gitignore new file mode 100644 index 00000000..5a0bf031 --- /dev/null +++ b/docs/.gitignore @@ -0,0 +1 @@ +/book diff --git a/docs/book.toml b/docs/book.toml new file mode 100644 index 00000000..5b15ed1b --- /dev/null +++ b/docs/book.toml @@ -0,0 +1,18 @@ +[book] +authors = ["Fluid Attacks"] +language = "en" +multilingual = false +src = "src" +title = "Makes" + +[output.html] +default-theme = "light" +edit-url-template = "https://github.com/fluidattacks/makes/edit/main/docs/{path}" +preferred-dark-theme = "ayu" +git-repository-url = "https://github.com/fluidattacks/makes" +git-repository-icon = "fa-github" +site-url = "/" + +[output.html.fold] +enable = false +level = 0 diff --git a/docs/src/README.md b/docs/src/README.md new file mode 100644 index 00000000..b6c9a6a9 --- /dev/null +++ b/docs/src/README.md @@ -0,0 +1,3 @@ +# 🦄 Makes + +A software supply chain framework powered by Nix. diff --git a/docs/src/SUMMARY.md b/docs/src/SUMMARY.md new file mode 100644 index 00000000..84b797da --- /dev/null +++ b/docs/src/SUMMARY.md @@ -0,0 +1,7 @@ +[Introduction](./README.md) + +# Reference + +# Security + +- [Supply Chain Levels for Software Artifacts](./security/slsa.md) diff --git a/docs/src/security/slsa.md b/docs/src/security/slsa.md new file mode 100644 index 00000000..dbcf8901 --- /dev/null +++ b/docs/src/security/slsa.md @@ -0,0 +1,125 @@ +The [SLSA framework](https://slsa.dev/) +helps organizations measure +the level of assurance +that the Software Artifacts they produce +actually contain and use what they intended (integrity), +by ensuring that the whole build and release process, +and all of the involved sources and dependencies +cannot be tampered with. + +In this document, +we use the +[version 0.1 of the specification](https://slsa.dev/spec/v0.1/requirements). + +Our current SLSA level is 0. +The following is a detail of the levels achieved +on each of the requirements: + +| Requirement | Level | +| :----------------------------- | :---: | +| Source - Version Controlled | 4 | +| Source - Verified History | 4 | +| Source - Retained Indefinitely | 4 | +| Source - Two Person Reviewed | 3 | + +For clarity, +this is how SLSA definitions map into our infrastructure: + +- **Source**: Git repository at: + [github.com/fluidattacks/makes][makes]. +- **Platform**: [GitHub Actions][github_actions], + [Makes][makes], + and the [Nix package manager][nix]. +- **Build service**: + [GitHub Actions][github_actions], + using GitHub hosted runners. +- **Build**: A Nix derivation. +- **Environment**: A sandbox + that [Chroot](https://en.wikipedia.org/wiki/Chroot)s + into an empty temporary directory, + provides private versions + of `/proc`, `/dev`, `/dev/shm`, and `/dev/pts`, + and uses a private PID, mount, network, IPC, and UTS namespace + to isolate itself from other processes in the system. +- **Steps**: Instructions declared + in the corresponding Makes configuration files + written using the Nix programming language + and shell scripting, versioned as-code in the _source_. + +# Source - Version controlled + +Every change to the source is tracked on GitHub, +using the Git version control system. + +- **Change history**: There exists a record + of the history of changes + that went into the revision. + Each change contains: + the identities of the uploader and reviewers (if any), + timestamps of the reviews (if any) and submission, + the change description/justification, + the content of the change, + and the parent revisions. + + For example: [PR 649](https://github.com/fluidattacks/makes/pull/649). + +- **Immutable reference**: + There exists a way to indefinitely reference a particular, + immutable revision. + For example: + [c61feb1be11abc4d7ffed52c660a45c57f06599c](https://github.com/fluidattacks/makes/commit/c61feb1be11abc4d7ffed52c660a45c57f06599c). + +# Source - Verified history + +Every change in the revision’s history +need to pass through a Pull Request. + +In order to approve a Pull Request +the reviewer need to be strongly authenticated into GitHub. +The authentication process requires 2FA, +and the dates of the change +are recorded in the Pull Request. + +Only users who were previously granted access +by a platform Admin can review Pull Requests. +External contributors can create a Pull Request +without any special privileges, +but it won't be merged +until reviewers submit their approval. + +For example: +[PR 649](https://github.com/fluidattacks/makes/pull/649). + +# Source - Retained indefinitely + +The revision and its change history +are preserved indefinitely +and cannot be deleted +or modified (not even with multi-party approval). +Additionally, +the main branch is protected +against accidental history overwrite +using GitHub's branch protection rules. + +At the moment, +no legal requirement +impedes us to preserve indefinitely our change history, +and no obliteration policy is in effect. +In fact, our source code is Free and Open Source Software: +Anyone can download or fork the repository. + +# Source - Two Person Reviewed + +Every change in the revision’s history +is agreed to by at least one trusted person +prior to submission +and each of these trusted persons +are authenticated into the platform (using 2FA) first. +Only project maintainers can merge Pull Requests +and therefore append a change into the revision's history. + + + +[github_actions]: https://docs.github.com/en/actions +[makes]: https://github.com/fluidattacks/makes +[nix]: https://nixos.org/ diff --git a/makes.nix b/makes.nix index 6908dd26..e2e01634 100644 --- a/makes.nix +++ b/makes.nix @@ -44,7 +44,10 @@ bin = [inputs.nixpkgs.hello]; }; makes = { - bin = [inputs.nixpkgs.just]; + bin = [ + inputs.nixpkgs.just + inputs.nixpkgs.mdbook + ]; source = [outputs."/cli/pypi"]; }; }; diff --git a/makes/docs/builder.sh b/makes/docs/builder.sh new file mode 100644 index 00000000..97add536 --- /dev/null +++ b/makes/docs/builder.sh @@ -0,0 +1 @@ +mdbook build --dest-dir "${out}" "${envDocs}" diff --git a/makes/docs/main.nix b/makes/docs/main.nix new file mode 100644 index 00000000..ed1d9c2a --- /dev/null +++ b/makes/docs/main.nix @@ -0,0 +1,12 @@ +{ + inputs, + makeDerivation, + projectPath, + ... +}: +makeDerivation { + name = "docs"; + env.envDocs = projectPath "/docs"; + builder = ./builder.sh; + searchPaths.bin = [inputs.nixpkgs.mdbook]; +} diff --git a/makes/tests/makeTemplate/test.yaml b/makes/tests/makeTemplate/test.yaml index c8071b1b..dbbe44da 100644 --- a/makes/tests/makeTemplate/test.yaml +++ b/makes/tests/makeTemplate/test.yaml @@ -12,6 +12,7 @@ testTitle: >- + ‘ ’ “ ” • – — ˜ ™ š › œ ž Ÿ ¡ ¢ £ ¤ ¥ ¦ § ¨ © ª « ¬ ­ ® ¯ ° ± ² ³ ´ µ ¶ · ¸ ¹ º » ¼ ½ ¾ ¿