Skip to content

Commit 594b2fc

Browse files
behnazh-wbehnazh-w
authored
docs: add policy related docs and improve examples (#284)
Signed-off-by: behnazh-w <behnaz.hassanshahi@oracle.com>
1 parent f3f9ecf commit 594b2fc

File tree

5 files changed

+209
-2
lines changed

5 files changed

+209
-2
lines changed

‎docs/source/_static/examples/micronaut-projects/micronaut-core/policies/micronaut-core.cue

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,11 @@
1+
{
2+
target: "micronaut-projects/micronaut-core",
3+
predicate: {
4+
invocation: {
5+
configSource: {
6+
uri: =~"^git\\+https://github.com/micronaut-projects/micronaut-core@refs/tags/v[0-9]+.[0-9]+.[0-9]+$"
7+
entryPoint: ".github/workflows/release.yml"
8+
}
9+
}
10+
}
11+
}

‎docs/source/_static/examples/oracle-quickstart/oci-micronaut/policies/oci-micronaut.dl

Lines changed: 49 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,49 @@
1+
/* Copyright (c) 2023 - 2023, Oracle and/or its affiliates. All rights reserved. */
2+
/* Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/. */
3+
4+
5+
#include "prelude.dl"
6+
7+
/**
8+
* This is an example policy for OCI Micronaut project.
9+
* See: https://github.com/oracle-quickstart/oci-micronaut
10+
*/
11+
12+
Policy("oci_micronaut_dependencies", parent, "") :-
13+
check_passed(parent, "mcn_build_service_1"),
14+
!violating_dependencies(parent, "mcn_build_service_1"), // There should not be any violating dependencies.
15+
verify_provenance(dependency, "micronaut-projects/micronaut-core").
16+
17+
// Projects that violate an expected check result.
18+
.decl violating_dependencies(parent: number, property: symbol)
19+
violating_dependencies(parent, property) :-
20+
is_check(property),
21+
transitive_dependency(parent, dependency), // note that since macaron by default does not traverse
22+
// to transitive, dependencies, in most cases this is
23+
// identical to `dependency(parent, repo)`.
24+
!check_passed(dependency, property),
25+
!exception_dependencies(dependency).
26+
27+
// Exceptions for violating dependencies.
28+
.decl exception_dependencies(dependency: number)
29+
exception_dependencies(dependency) :-
30+
is_repo(dependency, "mapstruct/mapstruct").
31+
32+
exception_dependencies(dependency) :-
33+
is_repo(dependency, "mysql/mysql-connector-j").
34+
35+
exception_dependencies(dependency) :-
36+
is_repo(dependency, "aws/aws-msk-iam-auth").
37+
38+
exception_dependencies(dependency) :-
39+
is_repo(dependency, "h2database/h2database").
40+
41+
// Projects that we expect to generate a provenance.
42+
.decl verify_provenance(repo_num: number, repo_name: symbol)
43+
verify_provenance(repo_num, repo_name) :-
44+
is_repo(repo_num, repo_name),
45+
check_passed(repo_num, "mcn_provenance_level_three_1"),
46+
check_passed(repo_num, "mcn_provenance_expectation_1").
47+
48+
// Apply the policy.
49+
apply_policy_to("oci_micronaut_dependencies", repo) :- is_repo(repo, "oracle-quickstart/oci-micronaut").

‎docs/source/_static/images/macaron_infrastructure.png

129 KB
Loading

‎docs/source/index.rst

Lines changed: 80 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,89 @@
11
.. Copyright (c) 2022 - 2023, Oracle and/or its affiliates. All rights reserved.
22
.. Licensed under the Universal Permissive License v 1.0 as shown at https://oss.oracle.com/licenses/upl/.
33
4+
.. _index:
5+
6+
.. meta::
7+
:description: macaron - A CI/CD security analysis tool for supply-chain attacks
8+
:keywords: CI/CD, SLSA, supply-chain security
9+
10+
=====================
411
Macaron documentation
512
=====================
613

14+
Software supply-chain attacks are becoming more prevalent as the systems get more complex, particularly with respect to the use of open-source
15+
third-party code. Attacks include stealing credentials, tampering with the
16+
code, tampering with the code repository, and tampering with the build system.
17+
It is crucial to have guarantees that the third-party code we rely on is the
18+
code we expect.
19+
20+
To tackle these problems, `Supply-chain Levels for Software Artifacts (SLSA or "salsa") <https://slsa.dev>`_ is created to improve the integrity and
21+
protection of the software supply-chain. Macaron can analyze a software
22+
repository to determine its SLSA level and provide supply-chain transparency of the build process.
23+
24+
--------
25+
Overview
26+
--------
27+
28+
Macaron is an analysis tool which focuses on the build process for an artifact and its dependencies. As the SLSA requirements
29+
are at a high-level, Macaron first defines these requirements as specific
30+
concrete rules that can be checked automatically. Macaron has a customizable checker platform that makes it easy to define checks that depend on each other.
31+
32+
-------------------------
33+
Current checks in Macaron
34+
-------------------------
35+
36+
The table below shows the current set of actionable checks derived from
37+
the requirements that are currently supported by Macaron.
38+
39+
.. note:: The current checks are designed based on `SLSA v0.1 <https://slsa.dev/spec/v0.1/>`_. Support for `SLSA v1.0 <https://slsa.dev/spec/v1.0/>`_ is currently under development.
40+
41+
.. list-table:: Mapping SLSA requirements to Macaron checks
42+
:widths: 20 40 40
43+
:header-rows: 1
44+
45+
* - SLSA level
46+
- SLSA spec v0.1
47+
- Concrete check
48+
* - 1
49+
- **Scripted build** - All build steps were fully defined in a “build script”.
50+
- Identify and validate build script(s).
51+
* - 1
52+
- **Provenance available** - The provenance is available.
53+
- Check for existence of SLSA provenance. If there are no SLSA provenance, the repo can still be compliant to level 1 given the build script is available.
54+
* - 2
55+
- **Build service** - All build steps are run using some build service (e.g. GitHub Actions)
56+
- Identify and validate the CI service(s) used for the build process.
57+
* - 3
58+
- **Trusted builders** - Guarantees the identification of the top-level build configuration used to initiate the build. The build is verified to be hermetic, isolated, parameterless, and executed in an ephemeral environment.
59+
- Identify and validate that the builder used in the CI pipeline is a trusted one.
60+
* - 3
61+
- **Build as code** - If a trusted builder is not present, this requirement determines that the build definition and configuration executed by the build service is verifiably derived from text file definitions stored in a version control system.
62+
- Identify and validate the CI service(s) used to build and deploy/publish an artifact.
63+
* - 3
64+
- **Provenance Level three** - Check whether the target has SLSA provenance level 3.
65+
- Use the `slsa-verifier <https://github.com/slsa-framework/slsa-verifier>`_ to attest to the subjects in the SLSA provenance that accompanies an artifact.
66+
* - 3
67+
- **Provenance expectation** - Check if the provenance meets an expectation.
68+
- The user can provide an expectation for the provenance as a CUE policy, which will be compared against the SLSA provenance.
69+
70+
----------------------
71+
How does Macaron work?
72+
----------------------
73+
74+
.. _fig_macaron:
75+
76+
.. figure:: _static/images/macaron_infrastructure.png
77+
:alt: Macaron infrastructure
78+
:align: center
79+
80+
Macaron's infrastucture
81+
82+
Macaron is designed based on a Zero Trust model. It analyzes a target repository as an external
83+
tool and requires minimal configurations. After cloning a repository, Macaron parses the CI
84+
configuration files and bash scripts that are triggered by the CI, creates call graphs and other
85+
intermediate representations as abstractions. Using such abstractions, Macaron implements concrete checks based on a security specification and verifies the desired properties.
86+
787
.. toctree::
888
:maxdepth: 1
989

‎docs/source/pages/using.rst

Lines changed: 69 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,8 @@ Using Macaron
99

1010
.. note:: The instructions below assume that you have setup you environment correctly to run Macaron (if not, please refer to :ref:`Installation Guide <installation-guide>`).
1111

12+
.. _analyze-action:
13+
1214
------------------------------------
1315
Analyzing a public Github repository
1416
------------------------------------
@@ -50,13 +52,45 @@ With the example above, the generated output reports can be seen here:
5052
- `micronaut-core.html <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.html>`__
5153
- `micronaut-core.json <../_static/examples/micronaut-projects/micronaut-core/analyze_with_repo_path/micronaut-core.json>`__
5254

55+
-------------------------------------------------
56+
Verifying provenance expectations in CUE language
57+
-------------------------------------------------
58+
59+
When a project generates SLSA provenances, you can add a build expectation in the form of a
60+
`Configure Unify Execute (CUE) <https://cuelang.org/>`_ policy to check the content of provenances. For instance, the expectation
61+
can specify the accepted GitHub Actions workflows that trigger a build, which can prevent using artifacts built from attackers
62+
workflows.
63+
64+
.. code-block:: shell
65+
66+
./run_macaron.sh analyze -pe micronaut-core.cue -rp https://github.com/micronaut-projects/micronaut-core -b 4.0.x -d 82d115b4901d10226552ac67b0a10978cd5bc603 --skip-deps
67+
68+
where ``micronaut-core.cue`` file can contain:
69+
70+
.. code-block:: javascript
71+
72+
{
73+
target: "micronaut-projects/micronaut-core",
74+
predicate: {
75+
invocation: {
76+
configSource: {
77+
uri: =~"^git\\+https://github.com/micronaut-projects/micronaut-core@refs/tags/v[0-9]+.[0-9]+.[0-9]+$"
78+
entryPoint: ".github/workflows/release.yml"
79+
}
80+
}
81+
}
82+
}
83+
84+
.. note::
85+
The provenance expectation is verified via the ``provenance_expectation`` check in Macaron. You can see the result of this check in the HTML or JSON report and see if the provenance found by Macaron meets the expectation CUE file.
86+
5387
----------------------
5488
Analyzing with an SBOM
5589
----------------------
5690

57-
Macaron can run the analysis against a `CycloneDX <https://cyclonedx.org/>`__ format SBOM, which contains all the necessary information of the target component and its dependencies. This use case is useful when you are running Macaron against a software component that is not available as a public GitHub repository but you still want to analyze the SLSA posture of its dependencies.
91+
Macaron can run the analysis against an existing SBOM in `CycloneDX <https://cyclonedx.org/>`_ which contains all the necessary information of the dependencies of a target repository. In this case, the dependencies will not be resolved automatically.
5892

59-
CycloneDX provides open-source SBOM generators for different types of project (e.g Maven, Gradle, etc) To know how you could generate an CycloneDX SBOM for your projects, please have a look at their `open-source organization <https://github.com/CycloneDX>`_.
93+
CycloneDX provides open-source SBOM generators for different types of project (e.g Maven, Gradle, etc). For instructions on generating a CycloneDX SBOM for your project, see `CycloneDX documentation <https://github.com/CycloneDX>`_.
6094

6195
For example, with `micronaut-core <https://github.com/micronaut-projects/micronaut-core>`_ at branch 4.0.x commit ``82d115b4901d10226552ac67b0a10978cd5bc603``, using the `CycloneDX Gradle plugin <https://github.com/CycloneDX/cyclonedx-gradle-plugin>`_ would give us the following `SBOM <./_static/micronaut-projects/micronaut-core/analyze_with_sbom/sbom.json>`_.
6296

@@ -101,3 +135,36 @@ With ``rest_of_args`` being the arguments to the ``analyze`` command (e.g. ``-b`
101135
The ``-lr`` flag configure Macaron to looks into ``path/to/boo/foo`` for local repositories. For more information, please see :ref:`Command Line Usage <cli-usage>`.
102136

103137
.. note:: If ``-lr`` is not provided, Macaron will looks inside ``<working_directory>/output/git_repos/local_repos/`` whenever you provide a local path to ``-rp``.
138+
139+
-------------------------
140+
Running the policy engine
141+
-------------------------
142+
143+
Macaron's policy engine accepts policies specified in `Datalog <https://en.wikipedia.org/wiki/Datalog>`_. An example policy
144+
can verify if a project and all its dependencies pass certain checks. We use `Soufflé <https://souffle-lang.github.io/index.html>`_
145+
as the Datalog engine in Macaron. Once you run the checks on a target project as described :ref:`here <analyze-action>`,
146+
the check results will be stored in ``macaron.db`` in the output directory. We can pass the check results to the policy
147+
engine and provide a Datalog policy file to be enforced by the policy engine.
148+
149+
We use `Micronaut MuShop <https://github.com/oracle-quickstart/oci-micronaut>`_ project as a case study to show how to run the policy engine.
150+
Micronaut MuShop is a cloud-native microservices example for Oracle Cloud Infrastructure. When we run Macaron on the Micronaut MuShop GitHub
151+
project, it automatically finds the project’s dependencies and runs checks for the top-level project and dependencies
152+
independently. For example, the build service check, as defined in SLSA, analyzes the CI configurations to determine if its artifacts are built
153+
using a build service. Another example is the check that determines whether a SLSA provenance document is available for an artifact. If so, it
154+
verifies whether the provenance document attests to the produced artifacts. For the Micronaut MuShop project, Macaron identifies 48 dependencies
155+
that map to 24 unique repositories and generates an HTML report that summarizes the check results.
156+
157+
Now we can run the policy engine over these results and enforce a policy:
158+
159+
.. code-block:: shell
160+
161+
./run_macaron.sh verify-policy -o outputs -d outputs/macaron.db --file oci-micronaut.dl
162+
163+
In this example, the Datalog policy file is provided in `oci-micronaut.dl <../_static/examples/oracle-quickstart/oci-micronaut/policies/oci-micronaut.dl>`__.
164+
This example policy can verify if the Micronaut MuShop project and all its dependencies pass the ``build_service`` check
165+
and the Micronaut provenance documents meets the expectation provided as a `CUE file <../_static/examples/micronaut-projects/micronaut-core/policies/micronaut-core.cue>`__.
166+
167+
Thanks to Datalog’s expressive language model, it’s easy to add exception rules if certain dependencies do not meet a
168+
requirement. For example, `the Mysql Connector/J <https://slsa.dev/spec/v0.1/requirements#build-service>`_ dependency in
169+
the Micronaut MuShop project does not pass the ``build_service`` check, but can be manually investigated and exempted if trusted. Overall, policies expressed in Datalog can be
170+
enforced by Macaron as part of your CI/CD pipeline to detect regressions or unexpected behavior.

0 commit comments

Comments
 (0)