From e7b0ec750f8fd6ee0111c7b8d24ca4c4c8cf6faf Mon Sep 17 00:00:00 2001 From: IngyHere Date: Tue, 19 Mar 2024 10:53:55 -0700 Subject: [PATCH 01/10] Issue #25: Initial addition of security scanning section focused on SCRUB. ... --- .../security/security-scanning/README.md | 242 ++++++++++++++++++ 1 file changed, 242 insertions(+) create mode 100644 docs/guides/software-lifecycle/security/security-scanning/README.md diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md new file mode 100644 index 000000000..b806e9d23 --- /dev/null +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -0,0 +1,242 @@ +# Security Scanning + +
Guide to scan code for security issues.
+ +## Introduction + +**Background**: Software security is critical in modern systems with application code at its root. Identifying and addressing vulnerabilities rapidly mitigates risk and limits the potential surface area of attacks. We recommend [NASA's SCRUB platform](https://github.com/nasa/scrub) to manage code scanning by identifying, orchestrating and aggregating security information. SCRUB's GitHub implementation wraps [CodeQL](https://codeql.github.com/) results into compact, curated reports that highlight security assessments and are suitable for ingestion by automated reporting tools. A small configuration is appended to an existing CodeQL configuration (`codeql-config.yml` file) that specifies security analyses and reporting properties. + +**Use Cases**: +- Finding and mitigating security risks in code, such as: + - unknown +- Scanning local client repositories to identify exploitable security risks. +- Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks. +- Streamlining management of known security considerations during codebase audits. + +--- + +## Prerequisites +To get the most out of `SCRUB`, you'll need: + +* Python 3 with the `pip` tool installed. +* (Optional) Familiarity with BASH and/or Python for potential customizations. +* (Optional) A GitHub repository supporting GitHub Actions. + +--- + +## Quick Start + +1. Install SCRUB: + + > ℹ️ **Note:** the SLIM project has customized the SCRUB tool to identify additional sensitive keywords such as IP addresses, file paths, and AWS information. These additions are currently [under review](https://github.com/Yelp/detect-secrets/pulls/perryzjc) by the detect-secrets team for merge into the tool's `main` codebase. Until then we recommend using our SLIM fork as described below. + + ```bash + pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp + ``` + +2. Execute a baseline scan: + + ```bash + detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline + ``` + +3. Review the `.secrets.baseline` file for any detected secrets via an audit: + + ```bash + detect-secrets audit .secrets.baseline + ``` + +Additional steps like whitelisting accepted values and false positives, establishing pre-commit hooks and/or enabling further automation are covered in detail below. + +--- + +## Step-by-Step Guide + +There are three recommended layers of protection we suggest you enable to ensure comprehensive security. Please see below sections for further details. + +### Table of Contents +- [Secrets Detection](#secrets-detection) + - [Introduction](#introduction) + - [Prerequisites](#prerequisites) + - [Quick Start](#quick-start) + - [Step-by-Step Guide](#step-by-step-guide) + - [Table of Contents](#table-of-contents) + - [Layer 1: Full Scan and Audit (Client-side)](#layer-1-full-scan-and-audit-client-side) + - [Steps](#steps) + - [Layer 2: Git Commit Scan (Client-side)](#layer-2-git-commit-scan-client-side) + - [Steps](#steps-1) + - [Layer 3: Server-side Push to GitHub.com](#layer-3-server-side-push-to-githubcom) + - [Steps](#steps-2) + - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) + - [Credits](#credits) + - [Feedback and Contributions](#feedback-and-contributions) + +### Client-side Scan and Audit +This layer directly scans the developer's local environment using the `detect-secrets` tool. After scanning, a baseline file containing detected secrets is generated. Developers can audit this file for detailed information on detected secrets. + +#### Steps +1. **Installation** + - Install the release version of [SCRUB](https://nasa.github.io/scrub/installation.html). + ```bash + pip3 install --upgrade --user nasa-scrub + ``` + +2. **Scanning** + - Scan all local files from the current directory and output results to a baseline file. + ```bash + detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline + ``` + +3. **Checking Results** + - View the results in the baseline file. + ```bash + ... + ``` + +4. **Analysis** + - Analyze results using the `audit` tool. + ```bash + ... + ``` + +[View more on SCRUB scanning configuration](https://nasa.github.io/scrub/configuration-inputs.html) + +> ℹ️ **Note**: If you've marked any secrets as true positives, make sure to remove all references to these secrets and rerun a full scan. + +### GitHub Actions Analysis on Push and Pull Request + +Code is scanned for security risks within the repository. It leverages [GitHub Action](https://github.com/features/actions). The scan is triggered during a push or pull request and any detected security vulnerabilities are reported while blocking merges or pushes to protected branches. + +#### Steps +1. **Workflow Creation** + - The first step is to create a `codeql.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below while ensuring the correct branch of your codebase is referenced. For example (from the [Slim Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml)): + +```yaml +name: "CodeQL" + +on: + push: + branches: [main, develop] + pull_request: + # The branches below must be a subset of the branches above + branches: [develop] + schedule: + # default branch on sundays at 5a + - cron: '0 5 * * 0' + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: write + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + # CodeQL supports ['cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby'] + # Learn more about CodeQL language support at https://git.io/codeql-language-support + language: ['python'] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + #config-file: ./.github/workflows/codeql/codeql-config.yml + languages: ${{ matrix.language }} + queries: security-and-quality, security-extended + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: ./path/to/local/query, your-org/your-repo/queries@main + + # ℹ️ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + #- run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + + - name: Post-Process Output + run: | + python3 -m pip install nasa-scrub + + results_dir=`realpath ${{ github.workspace }}/../results` + sarif_files=`find $results_dir -name '*.sarif'` + + for sarif_file in $sarif_files + do + output_file="$results_dir/$(basename $sarif_file .sarif).scrub" + + python3 -m scrub.tools.parsers.translate_results $sarif_file $output_file ${{ github.workspace }} scrub + done + + python3 -m scrub.tools.parsers.csv_parser $results_dir + + echo "RESULTS_DIR=$results_dir" >> $GITHUB_ENV + + + - name: Upload CodeQL Artifacts + uses: actions/upload-artifact@v4 + with: + name: codeql-artifacts + path: ${{ env.RESULTS_DIR }} + if-no-files-found: error + overwrite: true + retention-days: 15 +``` + > ℹ️ Explanation: The GitHub Action checks out code, installs necessary packages, checks for a baseline file, and scans the repository for secrets. If new secrets are detected, the build fails and provides guidance. + +After setting this up, GitHub will run the workflow during pushes or pull requests. If any new secrets are detected, the status check will fail and the user will be notified in the pull request. + +> ⚠️ Warning: The check ensures specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses [Layer 1](#layer-1-full-scan-and-audit-client-side) and [Layer 2](#layer-2-git-commit-scan-client-side) to mitigate issues in the first place. + +--- + +### Frequently Asked Questions (FAQ) + +- Q: **If security concerns are detected in my code, what should I do?** + + A: Follow these steps: + + - _Identify and Confirm:_ + - _Mitigate:_ . + - _Validate Scans:_ . + - _Commit:_ . + - _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. + +- Q: **Where can I find more configurations and options for `SCRUB`?** + + A: Refer to the official documentation for [SCRUB](https://nasa.github.io/scrub). + + +--- + +## Credits + +**Authorship**: +- Lyle Barner [@lylebarner](https://github.com/lylebarner) +- John Engelke [@ingyhere](http://github.com/ingyhere) + +**Acknowledgements**: +- [Rishi Verma](http://github.com/riverma) + +--- + +## Feedback and Contributions + +We value your feedback and contributions. Enhance and expand this guide by referring to our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). \ No newline at end of file From d01821bda1c814e8aa95e9db4ca71b189b25c922 Mon Sep 17 00:00:00 2001 From: IngyHere Date: Tue, 19 Mar 2024 11:13:00 -0700 Subject: [PATCH 02/10] Issue #25: Rough draft security scanning template. ... --- .../security/security-scanning/README.md | 32 ++++++++----------- 1 file changed, 14 insertions(+), 18 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index b806e9d23..5ad0fb259 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -27,52 +27,48 @@ To get the most out of `SCRUB`, you'll need: ## Quick Start 1. Install SCRUB: - - > ℹ️ **Note:** the SLIM project has customized the SCRUB tool to identify additional sensitive keywords such as IP addresses, file paths, and AWS information. These additions are currently [under review](https://github.com/Yelp/detect-secrets/pulls/perryzjc) by the detect-secrets team for merge into the tool's `main` codebase. Until then we recommend using our SLIM fork as described below. - + ```bash - pip install git+https://github.com/NASA-AMMOS/slim-detect-secrets.git@exp + pip install --upgrade nasa-scrub ``` 2. Execute a baseline scan: ```bash - detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline + scrub ... ``` -3. Review the `.secrets.baseline` file for any detected secrets via an audit: +3. Review the `foo` file to audit any reported security issues: ```bash - detect-secrets audit .secrets.baseline + vi ... ``` -Additional steps like whitelisting accepted values and false positives, establishing pre-commit hooks and/or enabling further automation are covered in detail below. +Additional steps such as customizing reports and/or enabling further automation are covered in detail below. --- ## Step-by-Step Guide -There are three recommended layers of protection we suggest you enable to ensure comprehensive security. Please see below sections for further details. +SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. Please see below sections for further details. ### Table of Contents -- [Secrets Detection](#secrets-detection) +- [Security Scanning](#security-scanning) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Quick Start](#quick-start) - [Step-by-Step Guide](#step-by-step-guide) - [Table of Contents](#table-of-contents) - - [Layer 1: Full Scan and Audit (Client-side)](#layer-1-full-scan-and-audit-client-side) + - [Client-side Scan and Audit](#client-side-scan-and-audit) - [Steps](#steps) - - [Layer 2: Git Commit Scan (Client-side)](#layer-2-git-commit-scan-client-side) - - [Steps](#steps-1) - - [Layer 3: Server-side Push to GitHub.com](#layer-3-server-side-push-to-githubcom) + - [GitHub.com Actions Analysis on Push and Pull Request](#githubcom-actions-analysis-on-push-and-pull-request) - [Steps](#steps-2) - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) - [Credits](#credits) - [Feedback and Contributions](#feedback-and-contributions) ### Client-side Scan and Audit -This layer directly scans the developer's local environment using the `detect-secrets` tool. After scanning, a baseline file containing detected secrets is generated. Developers can audit this file for detailed information on detected secrets. +The developer's local environment is scanned directly using the `SCRUB` tool. After scanning, a report containing detected security issues is generated. Developers can audit this report for detailed information on detected security concerns. #### Steps 1. **Installation** @@ -99,11 +95,11 @@ This layer directly scans the developer's local environment using the `detect-se ... ``` -[View more on SCRUB scanning configuration](https://nasa.github.io/scrub/configuration-inputs.html) +[View more on advanced SCRUB scan configuration](https://nasa.github.io/scrub/configuration-inputs.html) -> ℹ️ **Note**: If you've marked any secrets as true positives, make sure to remove all references to these secrets and rerun a full scan. +> ℹ️ **Note**: Any confirmed security issues should be addressed and mitigated before pushing to remote repositories. -### GitHub Actions Analysis on Push and Pull Request +### GitHub.com Actions Analysis on Push and Pull Request Code is scanned for security risks within the repository. It leverages [GitHub Action](https://github.com/features/actions). The scan is triggered during a push or pull request and any detected security vulnerabilities are reported while blocking merges or pushes to protected branches. From 05c7b172209226da0776b5e67712372ad7445f6e Mon Sep 17 00:00:00 2001 From: ingyhere Date: Tue, 19 Mar 2024 11:21:18 -0700 Subject: [PATCH 03/10] Issue #25: Minor text edit. ... --- .../software-lifecycle/security/security-scanning/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 5ad0fb259..078ad3666 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -1,6 +1,6 @@ # Security Scanning -
Guide to scan code for security issues.
+
Guide to code scanning for security issues.
## Introduction @@ -235,4 +235,4 @@ After setting this up, GitHub will run the workflow during pushes or pull reques ## Feedback and Contributions -We value your feedback and contributions. Enhance and expand this guide by referring to our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). \ No newline at end of file +We value your feedback and contributions. Enhance and expand this guide by referring to our [contribution guidelines](https://nasa-ammos.github.io/slim/docs/contribute/contributing/). From 00609c44fe8c35673812c5a93f9fac932f5a1782 Mon Sep 17 00:00:00 2001 From: Lyle Barner Date: Thu, 28 Mar 2024 10:00:49 -0700 Subject: [PATCH 04/10] Update README.md First cut at filling in the details on security scans --- .../security/security-scanning/README.md | 110 ++++++++---------- 1 file changed, 49 insertions(+), 61 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 078ad3666..2cfdcfeea 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -4,12 +4,15 @@ ## Introduction -**Background**: Software security is critical in modern systems with application code at its root. Identifying and addressing vulnerabilities rapidly mitigates risk and limits the potential surface area of attacks. We recommend [NASA's SCRUB platform](https://github.com/nasa/scrub) to manage code scanning by identifying, orchestrating and aggregating security information. SCRUB's GitHub implementation wraps [CodeQL](https://codeql.github.com/) results into compact, curated reports that highlight security assessments and are suitable for ingestion by automated reporting tools. A small configuration is appended to an existing CodeQL configuration (`codeql-config.yml` file) that specifies security analyses and reporting properties. +**Background**: Software security is critical in modern systems with application code at its root. Identifying and addressing vulnerabilities rapidly mitigates risk and limits the potential surface area of attacks. We recommend [NASA's SCRUB platform](https://github.com/nasa/scrub) to manage code scanning by identifying, orchestrating and aggregating security information. SCRUB's GitHub implementation wraps [CodeQL](https://codeql.github.com/) results into compact, curated reports that highlight security assessments and are suitable for ingestion by automated reporting tools. A small configuration is appended to an existing CodeQL configuration (`codeql-config.yml` file) that specifies security analyses and reporting properties. **Use Cases**: - Finding and mitigating security risks in code, such as: - - unknown + - Improper input validation + - Weak encryption + - Use of dangerous library functions - Scanning local client repositories to identify exploitable security risks. +- Identifying issues that may be difficult to identify via unit testing. - Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks. - Streamlining management of known security considerations during codebase audits. @@ -18,48 +21,25 @@ ## Prerequisites To get the most out of `SCRUB`, you'll need: -* Python 3 with the `pip` tool installed. -* (Optional) Familiarity with BASH and/or Python for potential customizations. -* (Optional) A GitHub repository supporting GitHub Actions. - ---- - -## Quick Start - -1. Install SCRUB: - - ```bash - pip install --upgrade nasa-scrub - ``` - -2. Execute a baseline scan: - - ```bash - scrub ... - ``` - -3. Review the `foo` file to audit any reported security issues: - - ```bash - vi ... - ``` - -Additional steps such as customizing reports and/or enabling further automation are covered in detail below. +* Python 3 with the `pip` tool installed +* Static analysis tools installed and ready for use + * CodeQL, SonarQube, and Pylint are some common examples +* (Optional) Familiarity with BASH and/or Python for potential customizations +* (Optional) A GitHub repository supporting GitHub Actions --- ## Step-by-Step Guide -SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. Please see below sections for further details. +SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. Please see below sections for further details. ### Table of Contents - [Security Scanning](#security-scanning) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - - [Quick Start](#quick-start) - [Step-by-Step Guide](#step-by-step-guide) - [Table of Contents](#table-of-contents) - - [Client-side Scan and Audit](#client-side-scan-and-audit) + - [Client-side Scan and Audit](#client-side-scan-and-analysis) - [Steps](#steps) - [GitHub.com Actions Analysis on Push and Pull Request](#githubcom-actions-analysis-on-push-and-pull-request) - [Steps](#steps-2) @@ -67,7 +47,7 @@ SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. - [Credits](#credits) - [Feedback and Contributions](#feedback-and-contributions) -### Client-side Scan and Audit +### Client-side Scan and Analysis The developer's local environment is scanned directly using the `SCRUB` tool. After scanning, a report containing detected security issues is generated. Developers can audit this report for detailed information on detected security concerns. #### Steps @@ -77,23 +57,26 @@ The developer's local environment is scanned directly using the `SCRUB` tool. Af pip3 install --upgrade --user nasa-scrub ``` -2. **Scanning** - - Scan all local files from the current directory and output results to a baseline file. - ```bash - detect-secrets scan --all-files --disable-plugin AbsolutePathDetectorExperimental --exclude-files '\.secrets.*' --exclude-files '\.git*' > .secrets.baseline - ``` +2. **Configuration** + - Create a `scrub.cfg` configuration file. This file must be populated with project specific configuration values, depending on the tool that is being used. More information can be found in the [SCRUB documentation](https://nasa.github.io/scrub/configuration.html). -3. **Checking Results** - - View the results in the baseline file. - ```bash - ... + ``` bash + scrub get-conf --output scrub.cfg ``` -4. **Analysis** - - Analyze results using the `audit` tool. - ```bash - ... - ``` +3. **Scanning** + - For more information about running SCRUB, refer to the [user documentation](https://nasa.github.io/scrub/usage.html) + + ```bash + scrub run + ``` + +4. **Checking Results** + - Review the `.scrub` file to audit any reported security issues: + + ```bash + vi .scrub/.scrub + ``` [View more on advanced SCRUB scan configuration](https://nasa.github.io/scrub/configuration-inputs.html) @@ -106,7 +89,11 @@ Code is scanned for security risks within the repository. It leverages [GitHub A #### Steps 1. **Workflow Creation** - The first step is to create a `codeql.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below while ensuring the correct branch of your codebase is referenced. For example (from the [Slim Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml)): - + - This workflow is based on the default CodeQL workflow file with three modifications: + 1. Under the *Initialize CodeQL* step, the `queries` entity has been added to enable all of the available security queries + 2. A new *Post-Process Output* step has been added to generate a CSV output file that may be easily ingested by other systems + 3. A new *Upload CodeQL Artifacts* step has been added to produce a set of archive files for each run + ```yaml name: "CodeQL" @@ -166,7 +153,7 @@ jobs: - name: Perform CodeQL Analysis uses: github/codeql-action/analyze@v3 - + - name: Post-Process Output run: | python3 -m pip install nasa-scrub @@ -184,8 +171,8 @@ jobs: python3 -m scrub.tools.parsers.csv_parser $results_dir echo "RESULTS_DIR=$results_dir" >> $GITHUB_ENV - - + + - name: Upload CodeQL Artifacts uses: actions/upload-artifact@v4 with: @@ -199,7 +186,7 @@ jobs: After setting this up, GitHub will run the workflow during pushes or pull requests. If any new secrets are detected, the status check will fail and the user will be notified in the pull request. -> ⚠️ Warning: The check ensures specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses [Layer 1](#layer-1-full-scan-and-audit-client-side) and [Layer 2](#layer-2-git-commit-scan-client-side) to mitigate issues in the first place. +> ⚠️ Warning: The check ensures specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses [Layer 1](#layer-1-full-scan-and-audit-client-side) and [Layer 2](#layer-2-git-commit-scan-client-side) to mitigate issues in the first place. --- @@ -208,21 +195,22 @@ After setting this up, GitHub will run the workflow during pushes or pull reques - Q: **If security concerns are detected in my code, what should I do?** A: Follow these steps: - - - _Identify and Confirm:_ - - _Mitigate:_ . - - _Validate Scans:_ . - - _Commit:_ . - - _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. - + 1. _Identify and Confirm:_ The first step is to confirm if the vulnerability is actually valid. Static analysis is not perfect and can sometimes generate false positives. Try to refrain from assessing severity and instead focus on determining the accuracy of the finding. + 2. _Assess Severity:_ After you have confirmed that the vulnerability is valid, now it's time to assess severity. This generally means answering two questions: "How difficult is this vulnerability to exploit?" and "What are the consequences if this vulnerability is exploited?" This is often a fairly nuanced discussion, but the overall goal is a thoughtful assessment of potential risks. + 3. _Mitigate:_ The next step is to decide what action is required. In an ideal world all security vulnerabilities would be addressed, but this is often not a reasonable expectation. Sometimes the risk posed by a vulnerability is low and the effort the rectify is high, so the risk is acceptable. Mitigations can take many forms and can range from accepting the risk (e.g. doing nothing) to fully rewriting modules to address the vulnerability. + 4. _Validate Scans:_ After a mitigation is in place, we need to confirm that the vulnerability has been closed. This can be done by rerunning the static analysis scan or implementing new unit test cases. Validation is completed + 5. _Commit:_ At this point you're ready to commit your code changes. Merge as you normally would. You may want to call out the security specific nature in your commit message to make users aware of the criticality. + 6. _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. You may also consider if it would be helpful to modify your project's coding standard to improve code quality. + + - Q: **Where can I find more configurations and options for `SCRUB`?** - + A: Refer to the official documentation for [SCRUB](https://nasa.github.io/scrub). --- -## Credits +## Credits **Authorship**: - Lyle Barner [@lylebarner](https://github.com/lylebarner) From 38e82d95de6776f526f8ee17f40a3e79facdc984 Mon Sep 17 00:00:00 2001 From: Lyle Barner Date: Thu, 28 Mar 2024 10:52:57 -0700 Subject: [PATCH 05/10] Update README.md Remove TOC --- .../security/security-scanning/README.md | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 2cfdcfeea..06576c242 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -33,20 +33,6 @@ To get the most out of `SCRUB`, you'll need: SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. Please see below sections for further details. -### Table of Contents -- [Security Scanning](#security-scanning) - - [Introduction](#introduction) - - [Prerequisites](#prerequisites) - - [Step-by-Step Guide](#step-by-step-guide) - - [Table of Contents](#table-of-contents) - - [Client-side Scan and Audit](#client-side-scan-and-analysis) - - [Steps](#steps) - - [GitHub.com Actions Analysis on Push and Pull Request](#githubcom-actions-analysis-on-push-and-pull-request) - - [Steps](#steps-2) - - [Frequently Asked Questions (FAQ)](#frequently-asked-questions-faq) - - [Credits](#credits) - - [Feedback and Contributions](#feedback-and-contributions) - ### Client-side Scan and Analysis The developer's local environment is scanned directly using the `SCRUB` tool. After scanning, a report containing detected security issues is generated. Developers can audit this report for detailed information on detected security concerns. From aba86ed27a967c6cf0380067e4ddfbd01452e4a5 Mon Sep 17 00:00:00 2001 From: ingyhere Date: Thu, 25 Apr 2024 09:40:39 -0700 Subject: [PATCH 06/10] Issue #25: Address suggestions for introduction. ... --- .../security/security-scanning/README.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 06576c242..a0a5c24e5 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -7,14 +7,15 @@ **Background**: Software security is critical in modern systems with application code at its root. Identifying and addressing vulnerabilities rapidly mitigates risk and limits the potential surface area of attacks. We recommend [NASA's SCRUB platform](https://github.com/nasa/scrub) to manage code scanning by identifying, orchestrating and aggregating security information. SCRUB's GitHub implementation wraps [CodeQL](https://codeql.github.com/) results into compact, curated reports that highlight security assessments and are suitable for ingestion by automated reporting tools. A small configuration is appended to an existing CodeQL configuration (`codeql-config.yml` file) that specifies security analyses and reporting properties. **Use Cases**: -- Finding and mitigating security risks in code, such as: +- Standardized security reports that enables rapid interchange of scanning tools. + - Streamlining management of known security considerations during codebase audits. +- Discovering security risks in code, such as: - Improper input validation - Weak encryption - Use of dangerous library functions + - Other issues that may be difficult to identify via unit testing. - Scanning local client repositories to identify exploitable security risks. -- Identifying issues that may be difficult to identify via unit testing. - Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks. -- Streamlining management of known security considerations during codebase audits. --- From 641ff187f895e1d5e69eb6c1615b502029fddea9 Mon Sep 17 00:00:00 2001 From: ingyhere Date: Thu, 25 Apr 2024 10:33:53 -0700 Subject: [PATCH 07/10] Update docs/guides/software-lifecycle/security/security-scanning/README.md Co-authored-by: Rishi Verma --- .../software-lifecycle/security/security-scanning/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index a0a5c24e5..3a1b728db 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -75,7 +75,7 @@ Code is scanned for security risks within the repository. It leverages [GitHub A #### Steps 1. **Workflow Creation** - - The first step is to create a `codeql.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below while ensuring the correct branch of your codebase is referenced. For example (from the [Slim Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml)): + - The first step is to create a `codeql.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below to your new file while ensuring the correct branch of your codebase is referenced. For example, the following configuration scans for CodeQL security and quality checks for Python language code. Note: a version of the below is also available through the [SLIM Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml): - This workflow is based on the default CodeQL workflow file with three modifications: 1. Under the *Initialize CodeQL* step, the `queries` entity has been added to enable all of the available security queries 2. A new *Post-Process Output* step has been added to generate a CSV output file that may be easily ingested by other systems From d9601874b7bb84378cdb60bdf9229d1c631336ff Mon Sep 17 00:00:00 2001 From: ingyhere Date: Thu, 25 Apr 2024 10:37:17 -0700 Subject: [PATCH 08/10] Issue #25: Remove non-applicable text ... --- .../software-lifecycle/security/security-scanning/README.md | 5 ----- 1 file changed, 5 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 3a1b728db..8dfaecde6 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -169,11 +169,6 @@ jobs: overwrite: true retention-days: 15 ``` - > ℹ️ Explanation: The GitHub Action checks out code, installs necessary packages, checks for a baseline file, and scans the repository for secrets. If new secrets are detected, the build fails and provides guidance. - -After setting this up, GitHub will run the workflow during pushes or pull requests. If any new secrets are detected, the status check will fail and the user will be notified in the pull request. - -> ⚠️ Warning: The check ensures specific lines of code that may contain sensitive information are not disclosed publicly. In GitHub Action logs only a yes/no indication of sensitive information appears. However, the surface area exists for potential attackers to readily identify sensitive information. Monitor your pull requests actively to respond and always ensure your team actively uses [Layer 1](#layer-1-full-scan-and-audit-client-side) and [Layer 2](#layer-2-git-commit-scan-client-side) to mitigate issues in the first place. --- From 9ea87657352822dd27c712f1789d0d92278d4bc2 Mon Sep 17 00:00:00 2001 From: IngyHere Date: Thu, 6 Jun 2024 13:43:09 -0700 Subject: [PATCH 09/10] Issue #25: Updates to resolve review concerns: Clarify wording, better indentation, add registry entry. More to come ... --- .../security/security-scanning/README.md | 237 +++++++++--------- static/data/slim-registry.json | 15 ++ 2 files changed, 135 insertions(+), 117 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 8dfaecde6..6b97049d4 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -1,6 +1,6 @@ # Security Scanning -
Guide to code scanning for security issues.
+
Guide to scanning code for security issues.
## Introduction @@ -8,12 +8,12 @@ **Use Cases**: - Standardized security reports that enables rapid interchange of scanning tools. - - Streamlining management of known security considerations during codebase audits. + - Streamlining management of known security considerations during codebase audits. - Discovering security risks in code, such as: - - Improper input validation - - Weak encryption - - Use of dangerous library functions - - Other issues that may be difficult to identify via unit testing. + - Improper input validation + - Weak encryption + - Use of dangerous library functions + - Other issues that may be difficult to identify via unit testing. - Scanning local client repositories to identify exploitable security risks. - Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks. @@ -40,23 +40,23 @@ The developer's local environment is scanned directly using the `SCRUB` tool. Af #### Steps 1. **Installation** - Install the release version of [SCRUB](https://nasa.github.io/scrub/installation.html). - ```bash - pip3 install --upgrade --user nasa-scrub - ``` + ```bash + pip3 install --upgrade --user nasa-scrub + ``` 2. **Configuration** - Create a `scrub.cfg` configuration file. This file must be populated with project specific configuration values, depending on the tool that is being used. More information can be found in the [SCRUB documentation](https://nasa.github.io/scrub/configuration.html). - ``` bash - scrub get-conf --output scrub.cfg - ``` + ``` bash + scrub get-conf --output scrub.cfg + ``` 3. **Scanning** - For more information about running SCRUB, refer to the [user documentation](https://nasa.github.io/scrub/usage.html) - ```bash - scrub run - ``` + ```bash + scrub run + ``` 4. **Checking Results** - Review the `.scrub` file to audit any reported security issues: @@ -75,100 +75,103 @@ Code is scanned for security risks within the repository. It leverages [GitHub A #### Steps 1. **Workflow Creation** - - The first step is to create a `codeql.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below to your new file while ensuring the correct branch of your codebase is referenced. For example, the following configuration scans for CodeQL security and quality checks for Python language code. Note: a version of the below is also available through the [SLIM Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml): - - This workflow is based on the default CodeQL workflow file with three modifications: - 1. Under the *Initialize CodeQL* step, the `queries` entity has been added to enable all of the available security queries - 2. A new *Post-Process Output* step has been added to generate a CSV output file that may be easily ingested by other systems - 3. A new *Upload CodeQL Artifacts* step has been added to produce a set of archive files for each run - -```yaml -name: "CodeQL" - -on: - push: - branches: [main, develop] - pull_request: - # The branches below must be a subset of the branches above - branches: [develop] - schedule: - # default branch on sundays at 5a - - cron: '0 5 * * 0' - -jobs: - analyze: - name: Analyze - runs-on: ubuntu-latest - permissions: - actions: write - contents: read - security-events: write - - strategy: - fail-fast: false - matrix: - # CodeQL supports ['cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby'] - # Learn more about CodeQL language support at https://git.io/codeql-language-support - language: ['python'] - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - with: - fetch-depth: 0 - # Initializes the CodeQL tools for scanning. - - name: Initialize CodeQL - uses: github/codeql-action/init@v3 - with: - #config-file: ./.github/workflows/codeql/codeql-config.yml - languages: ${{ matrix.language }} - queries: security-and-quality, security-extended - # If you wish to specify custom queries, you can do so here or in a config file. - # By default, queries listed here will override any specified in a config file. - # Prefix the list here with "+" to use these queries and those in the config file. - # queries: ./path/to/local/query, your-org/your-repo/queries@main - - # ℹ️ Command-line programs to run using the OS shell. - # 📚 https://git.io/JvXDl - - # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines - # and modify them (or add more) to build your code if your project - # uses a compiled language - - #- run: | - # make bootstrap - # make release - - - name: Perform CodeQL Analysis - uses: github/codeql-action/analyze@v3 - - - name: Post-Process Output - run: | - python3 -m pip install nasa-scrub - - results_dir=`realpath ${{ github.workspace }}/../results` - sarif_files=`find $results_dir -name '*.sarif'` - - for sarif_file in $sarif_files - do - output_file="$results_dir/$(basename $sarif_file .sarif).scrub" - - python3 -m scrub.tools.parsers.translate_results $sarif_file $output_file ${{ github.workspace }} scrub - done - - python3 -m scrub.tools.parsers.csv_parser $results_dir - - echo "RESULTS_DIR=$results_dir" >> $GITHUB_ENV - - - - name: Upload CodeQL Artifacts - uses: actions/upload-artifact@v4 - with: - name: codeql-artifacts - path: ${{ env.RESULTS_DIR }} - if-no-files-found: error - overwrite: true - retention-days: 15 -``` + - The first step is to create a `scrub.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below to your new file while ensuring the correct branch of your codebase is referenced. For example, the following configuration scans for CodeQL security and quality checks for Python language code. Note: a version of the below is also available through the [SLIM Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml): + - This workflow is based on the default CodeQL workflow file with three modifications: + 1. Under the *Initialize CodeQL* step, the `queries` entity has been added to enable all of the available security queries + 2. A new *Post-Process Output* step has been added to generate a CSV output file that may be easily ingested by other systems + 3. A new *Upload CodeQL Artifacts* step has been added to produce a set of archive files for each run + + ```yaml + name: "SCRUB" + + on: + push: + branches: [main] + pull_request: + # The branches below must be a subset of the branches above + branches: [main] + schedule: + # default branch on sundays at 5a UTC + - cron: '0 5 * * 0' + + jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: write + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + # This implementations uses CodeQL, but SCRUB can leverage other scan tools. + # CodeQL supports ['cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby'] + # Learn more about CodeQL language support at https://git.io/codeql-language-support + language: ['python'] + + steps: + - name: Checkout repository + uses: actions/checkout@v4 + with: + fetch-depth: 0 + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + # note that CodeQL + with: + # optional config file for scan tool, in this case CodeQL + # config-file: ./.github/workflows/codeql/codeql-config.yml + languages: ${{ matrix.language }} + # If you wish to specify custom queries, you can do so here or in a config file. + # By default, queries listed here will override any specified in a config file. + # Prefix the list here with "+" to use these queries and those in the config file. + # queries: ./path/to/local/query, your-org/your-repo/queries@main + queries: security-and-quality, security-extended + + # ℹ️ Command-line programs to run using the OS shell. + # 📚 https://git.io/JvXDl + + # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines + # and modify them (or add more) to build your code if your project + # uses a compiled language + + # - run: | + # make bootstrap + # make release + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + + - name: Post-Process Output + run: | + python3 -m pip install nasa-scrub + + results_dir=`realpath ${{ github.workspace }}/../results` + sarif_files=`find $results_dir -name '*.sarif'` + + for sarif_file in $sarif_files + do + output_file="$results_dir/$(basename $sarif_file .sarif).scrub" + + python3 -m scrub.tools.parsers.translate_results $sarif_file $output_file ${{ github.workspace }} scrub + done + + python3 -m scrub.tools.parsers.csv_parser $results_dir + + echo "RESULTS_DIR=$results_dir" >> $GITHUB_ENV + + + - name: Upload SCRUB Artifacts + uses: actions/upload-artifact@v4 + with: + name: scrub-artifacts + path: ${{ env.RESULTS_DIR }} + if-no-files-found: error + overwrite: true + retention-days: 15 + ``` --- @@ -177,12 +180,12 @@ jobs: - Q: **If security concerns are detected in my code, what should I do?** A: Follow these steps: - 1. _Identify and Confirm:_ The first step is to confirm if the vulnerability is actually valid. Static analysis is not perfect and can sometimes generate false positives. Try to refrain from assessing severity and instead focus on determining the accuracy of the finding. - 2. _Assess Severity:_ After you have confirmed that the vulnerability is valid, now it's time to assess severity. This generally means answering two questions: "How difficult is this vulnerability to exploit?" and "What are the consequences if this vulnerability is exploited?" This is often a fairly nuanced discussion, but the overall goal is a thoughtful assessment of potential risks. - 3. _Mitigate:_ The next step is to decide what action is required. In an ideal world all security vulnerabilities would be addressed, but this is often not a reasonable expectation. Sometimes the risk posed by a vulnerability is low and the effort the rectify is high, so the risk is acceptable. Mitigations can take many forms and can range from accepting the risk (e.g. doing nothing) to fully rewriting modules to address the vulnerability. - 4. _Validate Scans:_ After a mitigation is in place, we need to confirm that the vulnerability has been closed. This can be done by rerunning the static analysis scan or implementing new unit test cases. Validation is completed - 5. _Commit:_ At this point you're ready to commit your code changes. Merge as you normally would. You may want to call out the security specific nature in your commit message to make users aware of the criticality. - 6. _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. You may also consider if it would be helpful to modify your project's coding standard to improve code quality. + 1. _Identify and Confirm:_ The first step is to confirm if the vulnerability is actually valid. Static analysis is not perfect and can sometimes generate false positives. Try to refrain from assessing severity and instead focus on determining the accuracy of the finding. + 2. _Assess Severity:_ After you have confirmed that the vulnerability is valid, now it's time to assess severity. This generally means answering two questions: "How difficult is this vulnerability to exploit?" and "What are the consequences if this vulnerability is exploited?" This is often a fairly nuanced discussion, but the overall goal is a thoughtful assessment of potential risks. + 3. _Mitigate:_ The next step is to decide what action is required. In an ideal world all security vulnerabilities would be addressed, but this is often not a reasonable expectation. Sometimes the risk posed by a vulnerability is low and the effort the rectify is high, so the risk is acceptable. Mitigations can take many forms and can range from accepting the risk (e.g. doing nothing) to fully rewriting modules to address the vulnerability. + 4. _Validate Scans:_ After a mitigation is in place, we need to confirm that the vulnerability has been closed. This can be done by rerunning the static analysis scan or implementing new unit test cases. Validation is completed + 5. _Commit:_ At this point you're ready to commit your code changes. Merge as you normally would. You may want to call out the security specific nature in your commit message to make users aware of the criticality. + 6. _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. You may also consider if it would be helpful to modify your project's coding standard to improve code quality. - Q: **Where can I find more configurations and options for `SCRUB`?** @@ -195,8 +198,8 @@ jobs: ## Credits **Authorship**: -- Lyle Barner [@lylebarner](https://github.com/lylebarner) -- John Engelke [@ingyhere](http://github.com/ingyhere) +- [Lyle Barner](https://github.com/lylebarner) +- [John Engelke](http://github.com/ingyhere) **Acknowledgements**: - [Rishi Verma](http://github.com/riverma) diff --git a/static/data/slim-registry.json b/static/data/slim-registry.json index 6ec02dc1d..8c46786f2 100644 --- a/static/data/slim-registry.json +++ b/static/data/slim-registry.json @@ -154,6 +154,21 @@ "tools" ] }, + { + "title": "Code Security Scanning", + "uri": "/slim/docs/guides/software-lifecycle/security/security-scanning", + "category": "software-lifecycle", + "description": "A guide to scanning code for security issues using NASA's SCRUB tool.", + "tags": [ + "continuous-integration", + "devops", + "github", + "metrics", + "scanning", + "testing", + "tools" + ] + }, { "title": "GitHub Security Best Practices", "uri": "/slim/docs/guides/software-lifecycle/security/github-security", From 43d6b14562cb0ccd8d25207e533965b62b8df19e Mon Sep 17 00:00:00 2001 From: IngyHere Date: Thu, 6 Jun 2024 13:43:09 -0700 Subject: [PATCH 10/10] Issue #25: Mainly technical edits to support readability. Forthcoming there will be a semi-minor rewrite to clarify build requirements in the context of multiple languages. ... --- .../security/security-scanning/README.md | 26 +++++++++---------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/docs/guides/software-lifecycle/security/security-scanning/README.md b/docs/guides/software-lifecycle/security/security-scanning/README.md index 6b97049d4..5974c5999 100644 --- a/docs/guides/software-lifecycle/security/security-scanning/README.md +++ b/docs/guides/software-lifecycle/security/security-scanning/README.md @@ -7,24 +7,24 @@ **Background**: Software security is critical in modern systems with application code at its root. Identifying and addressing vulnerabilities rapidly mitigates risk and limits the potential surface area of attacks. We recommend [NASA's SCRUB platform](https://github.com/nasa/scrub) to manage code scanning by identifying, orchestrating and aggregating security information. SCRUB's GitHub implementation wraps [CodeQL](https://codeql.github.com/) results into compact, curated reports that highlight security assessments and are suitable for ingestion by automated reporting tools. A small configuration is appended to an existing CodeQL configuration (`codeql-config.yml` file) that specifies security analyses and reporting properties. **Use Cases**: -- Standardized security reports that enables rapid interchange of scanning tools. - - Streamlining management of known security considerations during codebase audits. +- Standardized security reports that enables rapid interchange of scanning tools + - Streamlining management of known security considerations during codebase audits - Discovering security risks in code, such as: - Improper input validation - Weak encryption - Use of dangerous library functions - Other issues that may be difficult to identify via unit testing. - Scanning local client repositories to identify exploitable security risks. -- Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks. +- Implementing a reporting loop in continuous integration (CI) pipelines using GitHub Actions to catch unforeseen risks --- ## Prerequisites -To get the most out of `SCRUB`, you'll need: +To get the most out of SCRUB, you'll need: * Python 3 with the `pip` tool installed * Static analysis tools installed and ready for use - * CodeQL, SonarQube, and Pylint are some common examples + * CodeQL, SonarQube and Pylint are some common examples * (Optional) Familiarity with BASH and/or Python for potential customizations * (Optional) A GitHub repository supporting GitHub Actions @@ -35,17 +35,17 @@ To get the most out of `SCRUB`, you'll need: SCRUB may be run locally or as a CI workflow action, such as in GitHub Actions. Please see below sections for further details. ### Client-side Scan and Analysis -The developer's local environment is scanned directly using the `SCRUB` tool. After scanning, a report containing detected security issues is generated. Developers can audit this report for detailed information on detected security concerns. +The developer's local environment is scanned directly using the SCRUB tool. After scanning, a report containing detected security issues is generated. Developers can audit this report for detailed information on detected security concerns. #### Steps 1. **Installation** - - Install the release version of [SCRUB](https://nasa.github.io/scrub/installation.html). + - Install the release version of [SCRUB](https://nasa.github.io/scrub/installation.html) ```bash pip3 install --upgrade --user nasa-scrub ``` 2. **Configuration** - - Create a `scrub.cfg` configuration file. This file must be populated with project specific configuration values, depending on the tool that is being used. More information can be found in the [SCRUB documentation](https://nasa.github.io/scrub/configuration.html). + - Create a `scrub.cfg` configuration file. This file must be populated with project specific configuration values, depending on the tool that is being used. More information can be found in the [SCRUB documentation](https://nasa.github.io/scrub/configuration.html) ``` bash scrub get-conf --output scrub.cfg @@ -69,13 +69,13 @@ The developer's local environment is scanned directly using the `SCRUB` tool. Af > ℹ️ **Note**: Any confirmed security issues should be addressed and mitigated before pushing to remote repositories. -### GitHub.com Actions Analysis on Push and Pull Request +### GitHub Actions Analysis on Push and Pull Request -Code is scanned for security risks within the repository. It leverages [GitHub Action](https://github.com/features/actions). The scan is triggered during a push or pull request and any detected security vulnerabilities are reported while blocking merges or pushes to protected branches. +Code is scanned for security risks within the repository. It leverages [GitHub Actions](https://github.com/features/actions). The scan is triggered during a push or pull request and any detected security vulnerabilities are reported while blocking merges or pushes to protected branches. #### Steps 1. **Workflow Creation** - - The first step is to create a `scrub.yaml` workflow file in the `.github/workflows` directory to define the GitHub action. Copy and paste the below to your new file while ensuring the correct branch of your codebase is referenced. For example, the following configuration scans for CodeQL security and quality checks for Python language code. Note: a version of the below is also available through the [SLIM Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml): + - The first step is to create a `scrub.yaml` workflow file in the `.github/workflows` directory to define a GitHub action. Copy and paste the below to your new file while ensuring the correct branch of your codebase is referenced. For example, the following configuration scans for CodeQL security and quality checks for Python language code. Note: a version of the below is also available through the [SLIM Python Starter Kit](https://github.com/NASA-AMMOS/slim-starterkit-python/blob/main/.github/workflows/codeql.yml): - This workflow is based on the default CodeQL workflow file with three modifications: 1. Under the *Initialize CodeQL* step, the `queries` entity has been added to enable all of the available security queries 2. A new *Post-Process Output* step has been added to generate a CSV output file that may be easily ingested by other systems @@ -175,7 +175,7 @@ Code is scanned for security risks within the repository. It leverages [GitHub A --- -### Frequently Asked Questions (FAQ) +## Frequently Asked Questions (FAQ) - Q: **If security concerns are detected in my code, what should I do?** @@ -188,7 +188,7 @@ Code is scanned for security risks within the repository. It leverages [GitHub A 6. _Educate and Prevent:_ To avoid such instances in the future, educate your team on the importance of code security and potential risks. Consider adopting practices or tools that identify risks early in development cycles. You may also consider if it would be helpful to modify your project's coding standard to improve code quality. -- Q: **Where can I find more configurations and options for `SCRUB`?** +- Q: **Where can I find more configurations and options for SCRUB?** A: Refer to the official documentation for [SCRUB](https://nasa.github.io/scrub).