update docs

Author: anthony-nhs

README.md

@@ -10,6 +10,7 @@ EPS DEV CONTAINERS
   - [Using local or pull request images in Visual Studio Code and GitHub Actions](#using-local-or-pull-request-images-in-visual-studio-code-and-github-actions)
 - [Common Makefile targets](#common-makefile-targets)
   - [Defined Targets](#targets)
+- [Anchore tools](#anchore-tools-syft-grype-grant)
 
 - [Project structure](#project-structure)
 - [Pull requests and merge to main process](#pull-requests-and-merge-to-main-process)
@@ -177,7 +178,18 @@ Check targets (`check.mk`)
 - `actionlint` - runs actionlint against GitHub Actions
 - `secret-scan` - runs git-secrets (including scanning history) against the repository
 - `guard-<ENVIRONMENT_VARIABLE>` - checks if an environment variable is set and errors if it is not
-- `zizmor` runs [zizmor](https://github.com/zizmorcore/zizmor) in the local directory to check github workflows and actions
+- `zizmor` - runs [zizmor](https://github.com/zizmorcore/zizmor) in the local directory to check github workflows and actions
+- `syft-generate-sbom` - uses syft to generate an sbom in cyclonedx-json format. This *does not* include dev dependencies. Outputs file to .sbom/sbom.cdx.json. 
+- `syft-generate-sbom-dev-dependencies`- uses syft to generate an sbom in cyclonedx-json format. This *DOES* include dev dependencies. Outputs file to .sbom/sbom.dev.cdx.json. 
+- `grype-scan` - Uses grype to scan for vulnerabilities. Uses an sbom generated by `syft-generate-sbom` target to find dependencies.
+- `grype-scan-dev-dependencies` - Uses grype to scan for vulnerabilities. Uses an sbom generated by `syft-generate-sbom-dev-dependencies` target to find dependencies.
+- `grype-scan-json` - Uses grype to scan for vulnerabilities. Uses an sbom generated by `syft-generate-sbom` target to find dependencies. Outputs file to .sbom/grype_analysis.json
+- `grype-scan-json-dev-dependencies` - Uses grype to scan for vulnerabilities. Uses an sbom generated by `syft-generate-sbom-dev-dependencies` target to find dependencies. Outputs file to .sbom/grype_analysis.dev.json
+- `grype-scan-local` - Uses grype to scan local folders for vulnerabilities. This is installed as a pre-commit hook in each project.
+- `grant-scan` - Uses scan to check for possible incompatible licenses. Uses an sbom generated by `syft-generate-sbom` target to find dependencies.
+- `grant-scan-dev-dependencies` - Uses scan to check for possible incompatible licenses. Uses an sbom generated by `syft-generate-sbom-dev-dependencies` target to find dependencies.
+- `grant-scan-json` - Uses scan to check for possible incompatible licenses. Uses an sbom generated by `syft-generate-sbom` target to find dependencies. Outputs file to .sbom/grant_analysis.json
+- `grant-scan-json-dev-dependencies` - Uses scan to check for possible incompatible licenses. Uses an sbom generated by `syft-generate-sbom-dev-dependencies` target to find dependencies. Outputs file to .sbom/grant_analysis.dev.json
 
 Credentials targets (`credentials.mk`)
 - `aws-configure` - configures an AWS SSO session
@@ -195,6 +207,28 @@ These are all changed to not run anything and will be removed in a future releas
 - `trivy-scan-java`
 - `trivy-scan-docker`
 
+# Anchore tools (syft, grype, grant)
+We use tools from [anchore](https://oss.anchore.com/docs/projects/) for various analysis. The tools we use are
+- syft to generate SBOM
+- grype to scan for vulnerabilities
+- grant to check for incompatible licenses
+
+## syft
+This is used to generate SBOM (software bill of materials) for dependencies. 
+There are makefile targets defined that run with most common settings we need. There should be no need to modify any configuration files for use
+
+# grype
+This scans for known vulnerabilities.   
+There are several makefile targets defined that can be used to run this - either outputting to console, or to a json file. It can also run for just runtime dependencies or include dev dependencies.   
+You may need to create a `.grype.yaml` with known accepted vulnerabilities in a project while we are waiting for downstream dependencies to update. Details of how to do this are documented at https://oss.anchore.com/docs/guides/vulnerability/filter-results/#ignore-specific-vulnerabilities-or-packages
+
+# grant
+This scans for incompatible licenses in dependencies.
+There are several makefile targets defined that can be used to run this - either outputting to console, or to a json file. It can also run for just runtime dependencies or include dev dependencies.   
+There is a default .grant.yaml file placed in home directories of devcontainers that lists acceptable licenses and known packages where the scanner incorrectly identified a license for a dependency.   
+If you need to modify this for a specific project, you must copy this to the root folder of the project and then modify it - eg `cp $HOME/.grant.yaml .`.   
+See https://oss.anchore.com/docs/guides/license/policies/ for details of what to put in the file.   
+
 # Project structure
 We have 5 types of dev container. These are defined under src
 

src/base/.devcontainer/.grant.yaml

@@ -0,0 +1,16 @@
+allow:
+  - MIT*
+  - Apache-2.0
+  - BSD-2-Clause
+  - BSD-3-Clause
+  - ISC
+  - 0BSD
+  - Unlicense
+  - CC0-1.0
+  - BlueOak-1.0.0
+  - BSD
+  - MPL-2.0
+  - CC-BY-4.0
+  - Python-2.0 
+ignore-packages:
+  - "case"

src/base/.devcontainer/Dockerfile

@@ -28,6 +28,7 @@ COPY --chmod=755 scripts/vscode_install.sh ${SCRIPTS_DIR}/${CONTAINER_NAME}/vsco
 USER vscode
 COPY --chown=vscode:vscode .tool-versions.asdf /home/vscode/.tool-versions.asdf
 COPY --chown=vscode:vscode .tool-versions /home/vscode/.tool-versions
+COPY --chown=vscode:vscode .grant.yaml /home/vscode/.grant.yaml
 
 ENV PATH="/home/vscode/.asdf/shims:/home/vscode/.guard/bin:$PATH"
 WORKDIR ${SCRIPTS_DIR}/${CONTAINER_NAME}

src/base/.devcontainer/Mk/check.mk

@@ -95,22 +95,59 @@ guard-%:
 zizmor:
 	zizmor --min-severity medium .
 
-generate-sbom:
+syft-generate-sbom:
 	syft \
 		--output cyclonedx-json=.sbom/sbom.cdx.json \
 		dir:./
 
-generate-sbom-dev-deps:
-	SYFT_JAVASCRIPT_INCLUDE_DEV_DEPENDENCIES=true syft \
+syft-generate-sbom-dev-dependencies:
+	SYFT_JAVASCRIPT_INCLUDE_DEV_DEPENDENCIES=true \
+	syft \
 		--output cyclonedx-json=.sbom/sbom.dev.cdx.json \
 		dir:./
 
-grype-scan: generate-sbom
-	grype .sbom/sbom.cdx.json \
-		 --output json=".sbom/grype_analysis.json"
-
-grant-scan: generate-sbom
+grype-scan: syft-generate-sbom
+	grype \
+		--fail-on high \
+		.sbom/sbom.cdx.json 
+
+grype-scan-dev-dependencies: syft-generate-sbom-dev-dependencies
+	grype \
+		--fail-on high \
+		.sbom/sbom.dev.cdx.json 
+
+grype-scan-json: syft-generate-sbom
+	grype \
+		--fail-on high \
+		.sbom/sbom.cdx.json \
+		--output json=".sbom/grype_analysis.json"
+
+grype-scan-json-dev-dependencies: syft-generate-sbom-dev-dependencies
+	grype \
+		--fail-on high \
+		.sbom/sbom.dev.cdx.json \
+		--output json=".sbom/grype_analysis.dev.json"
+
+grype-scan-local:
+	grype \
+		--fail-on high \
+		.
+grant-scan: syft-generate-sbom
+	grant check \
+		.sbom/sbom.cdx.json
+
+grant-scan-dev-dependencies: syft-generate-sbom-dev-dependencies
+	grant check \
+		.sbom/sbom.dev.cdx.json
+
+grant-scan-json: syft-generate-sbom
 	grant check .sbom/sbom.cdx.json \
 		--output json \
 		--quiet \
 		--output-file ".sbom/grant_analysis.json"
+
+grant-scan-json-dev-dependencies: syft-generate-sbom-dev-dependencies
+	grant check .sbom/sbom.dev.cdx.json \
+		--output json \
+		--quiet \
+		--output-file ".sbom/grant_analysis.dev.json"