govoplan/docs/SECURITY_AUDIT.md

Security Audit Toolchain

GovOPlaN uses a free/open-source-first audit toolchain that can run locally, inside a container, and in Gitea Actions.

Tools

• Semgrep: multi-language SAST, with GovOPlaN-specific local rules plus explicit public registry rulesets in CI/full runs.
• Bandit: Python AST security checks.
• Ruff S rules: fast flake8-bandit-compatible Python security linting.
• Gitleaks: committed-secret scanning.
• Trivy: filesystem dependency, secret, and misconfiguration scanning.
• pip-audit and npm audit: package vulnerability scanning from dependency manifests/locks.
• OSV-Scanner: recursive dependency vulnerability scan in full mode.
• jscpd: duplicated-code reports in full mode.
• Radon/Xenon: Python complexity reports and thresholds in full mode.

Local Usage

Build and run the toolbox from this repository:

cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode ci --scope current

Scan all sibling GovOPlaN repositories under /mnt/DATA/git:

cd /mnt/DATA/git/govoplan
tools/checks/security-audit/run.sh --mode full --scope govoplan

Reports are written to audit-reports/, which is intentionally ignored by git.

The wrapper tags the toolbox image by a fingerprint of the Dockerfile and requirements-audit.txt. If those inputs have not changed, subsequent runs reuse the existing local image instead of reinstalling all tools. The stable alias is govoplan/security-audit:local unless SECURITY_AUDIT_IMAGE is set.

Semgrep is installed separately in the toolbox image because current Semgrep packages pin Click to an affected 8.1.x line. The image upgrades Click after Semgrep installation and fails during build if Semgrep no longer starts with the patched Click version.

Force a cached rebuild:

tools/checks/security-audit/run.sh --mode ci --scope current --rebuild

Refresh from upstream base images and package ranges:

tools/checks/security-audit/run.sh --mode ci --scope current --update

Build or refresh the toolbox without running an audit:

tools/checks/security-audit/run.sh --mode quick --scope current --build-only
tools/checks/security-audit/run.sh --mode quick --scope current --update --build-only

Modes

• quick: local Semgrep rules, Bandit, Ruff security rules, Gitleaks.
• ci: quick plus Semgrep public registry rulesets, Trivy, pip-audit, npm audit.
• full: ci plus OSV-Scanner, jscpd, Radon, and Xenon.

Bandit and Ruff security reports are split by source kind. Production code under src/ is written to bandit.json and ruff-security.json and controls strict mode. Test code under tests/ is still scanned for visibility, but its findings are written separately to bandit-tests.json and ruff-security-tests.json so fixture passwords, assertions, and temporary paths do not hide the production baseline.

Gating

The initial Gitea workflow runs in report-only mode:

SECURITY_AUDIT_FAIL_ON_FINDINGS=0

This avoids blocking every push while the first baseline is reviewed. After the baseline is clean, switch the workflow to:

SECURITY_AUDIT_FAIL_ON_FINDINGS=1

or run locally with:

tools/checks/security-audit/run.sh --mode ci --scope current --strict

Audit Burndown Workflow

Treat Gitea issues as the active audit state. A full GovOPlaN audit should produce one tracker issue in add-ideas/govoplan and child issues in the repository that owns each fix.

Use the tracker issue for:

• report path, timestamp, mode, and scope
• scanner counts by category
• clean scanners and resolved findings
• links to child issues
• the next audit run target

Use child issues for concrete code or configuration changes. Apply source/security-audit to every issue created from a report, then add the most specific audit label:

• audit/quick-fix: narrow direct remediation
• audit/structural: behavior or architecture needs review
• audit/complexity: Radon/Xenon maintainability finding
• audit/duplication: jscpd duplication finding
• audit/false-positive: reviewed narrow false positive or accepted risk
• audit/needs-design: human decision needed before implementation

Keep active implementation status in issues instead of committing generated audit reports. audit-reports/ is ignored; quote the report directory and the important scanner counts in the tracker issue.

The jscpd step is intentionally scoped to application and test source. It excludes documentation snippets, package manifests, generated translations, public SVG assets, workflow YAML, and declarative backend schema JSON because those reports produce metadata or asset repetition rather than actionable source duplication. Keep exclusions narrow and create child issues for source-code clusters that cross module ownership or make behavior harder to change safely.

Image Freshness

The regular Security Audit workflow reuses the fingerprinted toolbox image when the Docker daemon is persistent, which is the normal case for the self-hosted Gitea runner using the host Docker socket. The separate Security Audit Toolbox Update workflow runs weekly with SECURITY_AUDIT_UPDATE=1; it pulls current base images and re-resolves the allowed tool version ranges into a refreshed local image.

Direct Host Usage

The container is the recommended path. For direct host usage, install the Python tools first:

cd /mnt/DATA/git/govoplan
python -m venv .venv
./.venv/bin/python -m pip install -r requirements-audit.txt
./.venv/bin/python -m pip install 'semgrep>=1.140,<2'
./.venv/bin/python -m pip install --upgrade --no-deps 'click>=8.3.3'

Then install the non-Python tools (gitleaks, trivy, osv-scanner, jscpd) through the host package manager or vendor instructions and run:

tools/checks/check-security-audit.sh --mode quick --scope current