Merge pull request #156 from NASA-AMMOS/issue-155

New guide on container security best practices

docs/guides/software-lifecycle/security/dependency-vulnerability-scanning/.pre-commit-config.yml

@@ -0,0 +1,10 @@
+repos:
+  - repo: local
+    hooks:
+      - id: grype-cve-scan
+        name: Grype Vulnerability Scan
+        description: Scans for dependency vulnerabilities. Fails if CRITICAL vulnerabilities detected.
+        entry: python -c "import os; import subprocess; import sys; os.environ['GRYPE_DB_AUTO_UPDATE'] = 'false'; result=subprocess.run(['grype', 'dir:.', '--fail-on', 'critical'], capture_output=True); print(result.stdout.decode()); print('CRITICAL level vulnerabilities found. To address issues, run scan via `grype dir:.`, then `git add` followed by `git commit` your fix or ignore via `git commit --no-verify`') if result.returncode != 0 else print('No CRITICAL level vulnerabilities found.'); sys.exit(result.returncode)"
+        language: system
+        verbose: true
+        stages: [pre-push]

docs/guides/software-lifecycle/security/dependency-vulnerability-scanning/README.mdx

@@ -0,0 +1,157 @@
+
+import CodeBlock from '@theme/CodeBlock';
+import PreCommitConfigSource from '!!raw-loader!./.pre-commit-config.yml';
+
+# Container Vulnerability Scanning
+
+<pre align="center">A guide to scanning containers and container repositories for security vulnerabilities both manually and automatically.</pre>
+
+![banner-image](/img/vulnerability-scanning-screen.png)
+
+## Introduction
+
+**Background**: To maintain the integrity and security of your containers in production environments, it's essential to monitor dependency vulnerabilities. Third-party software dependencies can harbor security vulnerabilities. This guide focuses on utilizing Grype, an open source vulnerability scanner, to proactively detect vulnerabilities in dependencies defined within container images as well as generally within repositories that use package managers.
+
+**Use Cases**:
+- Scanning container images for vulnerabilities during the development phase
+- Ensuring base container images are as vulnerability-free as possible
+- Scanning package-manager defined software dependencies (e.g. NPM, YARN, Maven, etc.) for vulnerabilities during the development phase
+- Automating vulnerability detection in repositories
+
+---
+
+## Prerequisites
+**Software:**
+- OCI compliant containers (e.g. Docker, Podman) or other package-manager software dependencies
+- `pre-commit` framework
+
+**Skills:**
+- Basic knowledge of Git hooks and Docker commands
+- Understanding of YAML for pre-commit configuration
+
+---
+
+## Quick Start
+
+**Run a local scan of your container's repository (folder containing the Dockerfile) using [Grype](https://github.com/anchore/grype)**
+
+```bash
+grype dir:.
+```
+
+**Run a local scan of a Docker image using Grype**
+
+First, build the Docker image:
+```bash
+docker build -t my-app:latest .
+```
+
+Then, scan the built Docker image:
+```bash
+grype my-app:latest
+```
+
+**⬇️ [Grype Scanning .pre-commit-config.yml](.pre-commit-config.yml)**
+
+Download the file above to access the pre-commit configuration file, which includes an example hook for Grype vulnerability scanning. This file should be placed within your local Git repository after installing the pre-commit framework.
+
+**⬇️ [Grype GitHub Action](https://github.com/marketplace/actions/anchore-container-scan)**
+
+GitHub Action for Grype vulnerability scanning. 
+
+---
+
+## Step-by-Step Guide
+
+### Step 1: Scan Locally for Container Vulnerabilities
+
+1. Ensure Grype is installed on your system. You can install Grype from [the official repository](https://github.com/anchore/grype).
+
+    ```bash
+    grype version
+    ```
+
+2. Perform a scan of the local repository for vulnerabilities. The below checks for vulnerabilities via any common package managers that are detected in your repository. See [Grype supported sources](https://github.com/anchore/grype?tab=readme-ov-file#supported-sources) for more information.
+
+    ```bash
+    grype dir:.
+    ```
+
+3. To scan a Docker image, first build the Docker image:
+
+    ```bash
+    docker build -t my-app:latest .
+    ```
+
+4. Then, perform a scan of the built Docker image:
+
+    ```bash
+    grype my-app:latest
+    ```
+
+5. If you find vulnerabilities, fix them via your package manager. 
+
+### Step 2: Setup Automated Local Scanning of Container Vulnerabilities
+
+⚠️ NOTE: We recommend installing this pre-commit hook only if you have downloaded grype, already scanned your repository and addressed any vulnerabilities.
+
+⚠️ NOTE: The automated scan described below will NOT check for image vulnerabilities, rather, it uses the package dependency capability of Grype to look for third-party dependencies via `grype dir:.`
+
+The below steps, once enacted, will ensure that any local `git push` actions taken will be followed by an automated vulnerability scan. If vulnerabilities at the CRITICAL level are found, the push will be blocked by default.
+
+1. Install the pre-commit framework via Python:
+   ```bash
+   pip install pre-commit
+   ```
+2. Create a `.pre-commit-config.yaml` file in the root directory of your Git repository with the following content for Grype scanning:
+   <CodeBlock language="yaml">{PreCommitConfigSource}</CodeBlock>
+
+3. Initialize pre-commit in your repository with the new configuration:
+   ```bash
+   pre-commit install
+   ```
+
+4. Grype-based vulnerability scanning should run every time a `git push` is invoked. The push will be blocked if CRITICAL level vulnerabilities are found and will ask the developer to fix them prior to committing. Otherwise a report will be provided for reference. 
+
+### Step 3: Set Up Automated Repository Scanning
+
+For GitHub users, we recommend:
+   - Installing the official Grype GitHub action to set up automated dependency vulnerability scanning. The tool is available [at this link](https://github.com/marketplace/actions/anchore-container-scan).
+   - Setting up GitHub's official Dependabot action to also look for vulnerabilities. See our [GitHub Security Guide](/docs/guides/software-lifecycle/security/github-security) on this. 
+
+---
+
+## Frequently Asked Questions (FAQ)
+
+**Q: What happens if the pre-commit scan finds vulnerabilities?**
+
+A: The pre-commit hook will prevent you from committing changes until the vulnerabilities are resolved. The scan is set to alert only for `critical` vulnerabilities by default to minimize disruption.
+
+**Q: What if I want to skip the pre-commit scan temporarily?**
+
+A: You can bypass the hook by using the `--no-verify` flag with the `git commit` command, though this is generally not recommended.
+
+**Q: Is it possible to run vulnerability scans without pre-commit hooks?**
+
+A: Yes, you can incorporate scans into your CI/CD pipeline or utilize other repository scanning tools, which can prevent pushing vulnerable code.
+
+**Q: What's the difference between Grype and GitHub's Dependabot? Why do I need both?**
+
+A: Grype relies on free and open software vulnerability databases whereas GitHub's Dependabot may be using proprietary methods. In our testing, we've found some non-overlapping vulnerabilities that are sometimes found in one tool but not the other.
+
+---
+
+## Credits 
+
+**Authorship**:
+- [Rishi Verma](https://www.github.com/riverma)
+
+**Acknowledgements**:
+* OPERA SDS Project for implementation guidance
+* [@ddalton-swe](https://github.com/ddalton-swe) for tool suggestions
+
+---
+
+## Feedback and Contributions
+
+We welcome feedback and contributions to enhance this guide further. Please refer to our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/).

package.json

@@ -21,6 +21,7 @@
     "bootstrap": "^5.3.0",
     "clsx": "^1.2.1",
     "prism-react-renderer": "^1.3.5",
+    "raw-loader": "^4.0.2",
     "react": "^17.0.2",
     "react-bootstrap": "^2.8.0",
     "react-dom": "^17.0.2"

yarn.lock

@@ -6649,6 +6649,14 @@ [email protected]:
     iconv-lite "0.4.24"
     unpipe "1.0.0"
 
+raw-loader@^4.0.2:
+  version "4.0.2"
+  resolved "https://registry.yarnpkg.com/raw-loader/-/raw-loader-4.0.2.tgz#1aac6b7d1ad1501e66efdac1522c73e59a584eb6"
+  integrity sha512-ZnScIV3ag9A4wPX/ZayxL/jZH+euYb6FcUinPcgiQW0+UBtEv0O6Q3lGd3cqJ+GHH+rksEv3Pj99oxJ3u3VIKA==
+  dependencies:
+    loader-utils "^2.0.0"
+    schema-utils "^3.0.0"
+
 [email protected], rc@^1.2.8:
   version "1.2.8"
   resolved "https://registry.yarnpkg.com/rc/-/rc-1.2.8.tgz#cd924bf5200a075b83c188cd6b9e211b7fc0d3ed"