Merge pull request #902 from kamadorueda/main

feat(back): #901 add slsa docs

.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:

.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

docs/.gitignore

@@ -0,0 +1 @@
+/book

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

docs/src/README.md

@@ -0,0 +1,3 @@
+# 🦄 Makes
+
+A software supply chain framework powered by Nix.

docs/src/SUMMARY.md

@@ -0,0 +1,7 @@
+[Introduction](./README.md)
+
+# Reference
+
+# Security
+
+- [Supply Chain Levels for Software Artifacts](./security/slsa.md)

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.
+
+<!-- References -->
+
+[github_actions]: https://docs.github.com/en/actions
+[makes]: https://github.com/fluidattacks/makes
+[nix]: https://nixos.org/

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"];
     };
   };

makes/docs/builder.sh

@@ -0,0 +1 @@
+mdbook build --dest-dir "${out}" "${envDocs}"

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];
+}

makes/tests/makeTemplate/test.yaml

@@ -12,6 +12,7 @@ testTitle: >-
 
 
 
+
   	‘	’	“	”	•	–	—	˜	™	š	›	œ		ž	Ÿ
    	¡	¢	£	¤	¥	¦	§	¨	©	ª	«	¬	­	®	¯
   °	±	²	³	´	µ	¶	·	¸	¹	º	»	¼	½	¾	¿