Issue #25: Initial addition of security scanning section focused on S…

…CRUB. ...

docs/guides/software-lifecycle/security/security-scanning/README.md

@@ -0,0 +1,242 @@
+# Security Scanning
+
+<pre align="center">Guide to scan code for security issues.</pre>
+
+## 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/).