diff --git a/docs/release/trg-0/trg-8-01.md b/docs/release/trg-0/trg-8-01.md new file mode 100644 index 00000000000..5749266742c --- /dev/null +++ b/docs/release/trg-0/trg-8-01.md @@ -0,0 +1,112 @@ +--- +title: TRG 8.01 - CodeQL +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Draft | 01-Mar-2024 | Draft release | + +## Why + +Use CodeQL for deep, static code analysis to identify vulnerabilities and improve code quality across a wide range of programming languages. + +## Description + +Use CodeQL for all repos with classic code (e.g., C#, Java) without exception. Do not use it for documentation-only or pure IaC repos; it's intended solely for analyzing classic code vulnerabilities. Exclude files as necessary. + +The GitHub Actions configuration must include the following triggers: + +- `workflow_dispatch`: Manual workflow execution. +- `schedule`: Schedule the workflow to run at least once a week with `0 0 * * 0`. +- `push` and `pull_request`: Activate the workflow on both push and pull request events targeting the branch that contains the code for the currently supported version, which may not necessarily be the `main` branch. This is the branch from which new releases will be made. + +Findings appear in the GitHub Advanced Security Dashboard. Dismiss high/error findings as non-exploitable or false positives with required justification in the vulnerability alert. + +:::caution + +Address high severity findings; it is recommended to also address medium severity findings. + +::: + +You can tailor the failure conditions (`fail-on`) for high severity issues in the workflow to suit your team's preferences. + +Adjust your code's language and build settings as indicated within the workflow comments. + +Example CodeQL workflow: + +```yml +name: "CodeQL" + +on: + push: + branches: ["main"] + paths-ignore: + - "**/*.md" + - "**/*.txt" + pull_request: + # The branches below must be a subset of the branches above + branches: ["main"] + paths-ignore: + - "**/*.md" + - "**/*.txt" + schedule: + - cron: "0 0 * * 0" + workflow_dispatch: + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + timeout-minutes: 360 + permissions: + actions: read + contents: read + security-events: write + + strategy: + fail-fast: false + matrix: + language: ["java"] # Define languages here + # CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python', 'ruby', 'swift' ] + # Use only 'java' to analyze code written in Java, Kotlin or both + # Use only 'javascript' to analyze code written in JavaScript, TypeScript or both + # Learn more about CodeQL language support at https://aka.ms/codeql-docs/language-support + + steps: + - name: Checkout repository + uses: actions/checkout@v3 + + # Initializes the CodeQL tools for scanning. + - name: Initialize CodeQL + uses: github/codeql-action/init@v2 + with: + 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 + + # For more details on CodeQL's query packs, refer to: https://docs.github.com/en/code-security/code-scanning/automatically-scanning-your-code-for-vulnerabilities-and-errors/configuring-code-scanning#using-queries-in-ql-packs + # Use +security-extended,security-and-quality for wider security and better code quality + queries: +security-extended,security-and-quality + + # Autobuild attempts to build any compiled languages (C/C++, C#, Go, Java, or Swift) + # Automates dependency installation for Python, Ruby, and JavaScript, optimizing the CodeQL analysis setup + # If this step fails, then you should remove it and run the build manually (see below) + - name: Autobuild + uses: github/codeql-action/autobuild@v2 + + # ℹī¸ Command-line programs to run using the OS shell. + # 📚 See https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idstepsrun + + # If the Autobuild fails above, remove it and uncomment the following three lines modify them (or add more) to build your code if your project, please refer to the EXAMPLE below for guidance + + # - run: | + # echo "Run, Build Application using script" + # ./location_of_script_within_repo/buildscript.sh + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{matrix.language}}" + fail-on: error +``` diff --git a/docs/release/trg-0/trg-8-03.md b/docs/release/trg-0/trg-8-03.md new file mode 100644 index 00000000000..de6d30ce62f --- /dev/null +++ b/docs/release/trg-0/trg-8-03.md @@ -0,0 +1,83 @@ +--- +title: TRG 8.03 - KICS +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Draft | 01-Mar-2024 | Draft release | + +## Why + +KICS is deployed for comprehensive scanning of Infrastructure as Code (IaC) files, ensuring secure and best-practice configurations across various IaC frameworks. + +## Description + +KICS is essential for repositories exclusively containing Infrastructure as Code (IaC) files, such as Terraform, CloudFormation, Kubernetes, GitHub Actions, and Helm charts. It's not applicable to traditional programming languages or documentation-only repositories. Exclude non-IaC files as necessary. + +Configure your GitHub Actions to include: + +- `workflow_dispatch`: Manual workflow execution. +- `schedule`: Schedule the workflow to run at least once a week with `0 0 * * 0`. +- `push` and `pull_request`: Targets the branch that holds the IaC files intended for current deployments, which might not always be the `main` branch. + +Findings appear in the GitHub Advanced Security Dashboard. Dismiss high/error findings as non-exploitable or false positives with required justification in the vulnerability alert. + +:::caution + +Address high severity findings; it is recommended to also address medium severity findings. + +::: + +You can tailor the failure conditions (`fail_on`) for high severity issues in the workflow to suit your team's preferences. + +Example KICS workflow: + +```yml +name: KICS + +on: + push: + branches: ["main"] + paths-ignore: + - "**/*.md" + - "**/*.txt" + pull_request: + # The branches below must be a subset of the branches above + branches: ["main"] + paths-ignore: + - "**/*.md" + - "**/*.txt" + schedule: + - cron: "0 0 * * 0" + workflow_dispatch: + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + steps: + - name: Checkout repo + uses: actions/checkout@v3 + + - name: Run KICS Scan with SARIF result + uses: checkmarx/kics-github-action@v1.7.0 + with: + path: "." # Scanning directory . + output_path: kicsResults/ # Output path for SARIF results + output_formats: "sarif" # Output format + # ignore_on_exit: results # Ignore the results and return exit status code 0 unless a KICS engine error happens + fail_on: high # If you want your pipeline to fail only on high severity results and KICS engine execution errors + # exclude_paths: "terraform/gcp/big_data.tf,terraform/azure" # Exclude paths or files from scan + # exclude_queries: 0437633b-daa6-4bbc-8526-c0d2443b946e # Exclude accepted queries from the build + disable_secrets: true # No secret scanning + + - name: Upload SARIF file + uses: github/codeql-action/upload-sarif@v2 + with: + sarif_file: kicsResults/results.sarif +``` diff --git a/docs/release/trg-0/trg-8-04.md b/docs/release/trg-0/trg-8-04.md new file mode 100644 index 00000000000..656281cf780 --- /dev/null +++ b/docs/release/trg-0/trg-8-04.md @@ -0,0 +1,25 @@ +--- +title: TRG 8.04 - GitGuardian +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Draft | 04-Mar-2024 | Draft release | + +## Why + +GitGuardian excels at detecting and preventing leaks of sensitive data in your code repositories, such as API keys, passwords, and other secrets. This can help you avoid security breaches and comply with data privacy regulations. + +## Description + +GitGuardian is integrated via its GitHub App, enabling automated secret scanning of our repositories. Each pull request undergoes a scan. If a potential secret is detected, the commit's author receives an immediate email notification. + +If a secret is suspected, the pull request will be locked. Immediate action is required regarding the potential secret due to the high risk associated with exposing secrets. + +:::caution + +Address all findings. + +::: + +The email contains a _temporary **link**_, allowing the author to either **report** the detected secret or **mark it as a false positive**, streamlining the review process for software engineers. diff --git a/docs/release/trg-0/trg-8-05.md b/docs/release/trg-0/trg-8-05.md new file mode 100644 index 00000000000..91b3fbd8a71 --- /dev/null +++ b/docs/release/trg-0/trg-8-05.md @@ -0,0 +1,76 @@ +--- +title: TRG 8.05 - Trivy +--- + +| Status | Created | Post-History | +|--------|-------------|--------------------------------------| +| Draft | 04-Mar-2024 | Draft release | + +## Why + +Trivy scans our Docker containers to accurately identify and remediate vulnerabilities in OS packages and application dependencies, ensuring our environment remains secure. + +## Description + +Trivy should be used if your project or repository builds containers and publishes them to Docker Hub. + +Configure your GitHub Actions to include: + +- `workflow_dispatch`: Manual workflow execution. +- `schedule`: Schedule the workflow to run at least once a week with `0 0 * * 0`. + +Because Trivy scans the published image on Docker Hub, running it on a `schedule` suffices, removing the necessity to execute it on every push and pull request. Optionally, the local build in the pipeline run can be scanned, using the `push` and `pull_request` triggers for these scans. + +In the Trivy workflow, the Docker Hub image scanned must be the currently supported version, not necessarily the `latest` image. + +If multiple Docker images, such as frontend and backend, are published from the repository, configure a scan for each image either by using the `matrix` option or by duplicating the necessary steps from the example workflow. + +Findings appear in the GitHub Advanced Security Dashboard. Dismiss high/error findings as non-exploitable or false positives with required justification in the vulnerability alert. + +:::caution + +Address high severity findings; it is recommended to also address medium severity findings. + +Due to IP considerations, base images with findings must not be updated arbitrarily, as outlined in [TRG4](https://eclipse-tractusx.github.io/docs/release/trg-4/trg-4-02). + +::: + +You can tailor the failure conditions (`exit-code`, `severity`) for high severity issues in the workflow to suit your team's preferences. + +Example Trivy workflow: + +```yml +name: "Trivy" + +on: + schedule: + - cron: "0 0 * * 0" + workflow_dispatch: + + +jobs: + analyze: + name: Analyze + runs-on: ubuntu-latest + permissions: + actions: read + contents: read + security-events: write + + steps: + - name: Run Trivy vulnerability scanner + uses: aquasecurity/trivy-action@0.18.0 + with: + image-ref: "tractusx/:" # Pull image from Docker Hub and run Trivy vulnerability scanner + format: "sarif" + output: "trivy-results.sarif" + exit-code: "1" # Trivy exits with code 1 if vulnerabilities are found, causing the workflow step to fail. + severity: "CRITICAL,HIGH" # While vulnerabilities of all severities are reported in the SARIF output, the exit code and workflow failure are triggered only by these specified severities (CRITICAL or HIGH). + hide-progress: false + + - name: Upload Trivy scan results to GitHub Security tab + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: "trivy-results.sarif" +```