Enable Static Code Analysis

This runbook describes how to use the new static code analysis workflow which scans repositories using multiple tools:

• Trivy for vulnerabilities and misconfigurations
  
• Terraform checks including tflint, terraform validate, and terraform fmt for Terraform-specific repositories
  

This document is informational only and does not embed or define any CI configuration files.

---

Creating the workflow

1. Create a job that uses the reusable workflow from the NVVS DevOps GitHub Actions repository (in .github/workflows/static-code-analysis.yml).
2. Configure the job to:
   • Accept a path to a Trivy ignore file
   • Optionally set the REPO_TYPE variable to 'non-tf' to disable Terraform-specific checks
3. Save the workflow file.

The workflow will now run as its own CI job alongside any other static analysis jobs.

jobs:
  static-code-analysis:
    name: static-code-analysis
    uses: ministryofjustice/nvvs-devops-github-actions/.github/workflows/terraform-trivy.yml@v1
    permissions:
      actions: read
      contents: read
      pull-requests: write
      security-events: write
    with:
      TRIVY_IGNORES: '.trivyignore.yaml'
      REPO_TYPE: 'tf' # or 'non-tf' to skip Terraform-specific checks

---

How CI merge blocking works

1. Enable branch protection rules on the target branch:
   • The following status check is added in the branch protection rule and required to pass before merging
     • Static Code Analysis / Scan Status
2. Open a pull request.
3. GitHub Actions automatically runs all configured checks (trivy, and tflint, validate fmt checks for tf repos).
4. The workflow evaluates Terraform code for vulnerabilities and misconfigurations.
5. If Trivy reports high or critical findings:
   • The Trivy job fails.
   • The pull request cannot be merged.
6. The pull request becomes mergeable only after:
   • The issue is fixed in code, or
   • A reviewed Trivy exception is added.

---

How to add safe exceptions

Trivy supports ignore files to document approved security exceptions.

1. Create a Trivy ignore file in the root of the repository (must be .trivyignore.yaml) and pass as a parameter to the reusable workflow.
2. Use the ignore file to suppress:
   • Specific vulnerability IDs
   • Specific Terraform misconfiguration checks and for specific paths example.
3. Where supported, prefer resource-level exclusions (for example, inline Terraform annotations) to limit the scope of exceptions and avoid impacting the entire repository/path.
4. Every exception must:
   • Be intentional
   • Be reviewed during pull request review
   • Have a clear justification
   • Be removed once remediation is complete

Exceptions are evaluated every time the workflow runs.

Expected workflow after enabling Trivy

After completing the steps above:

• Trivy runs automatically on pull requests + additional tf checks depending on the repo type.
• Security findings are visible in Github Code Scanning (a comment with relevant link will appear on pr)
• High and critical issues block merges Via branch protection rules
• Approved exceptions are explicit and reviewable

---

Ownership and review

• Owner: NVVS DevOps
• Slack: #nvvs-devops
• Review this runbook every 6 months or after CI changes

This page was last reviewed on 13 January 2026. It needs to be reviewed again on 13 July 2026 by the page owner #nvvs-devops .