security-review-commons

Security Review Commons

Portable, auditable code-security review core with thin adapters for OpenCode and Codex.

Status

This repository implements a phase-4 local foundation with audit-as-assurance-mode:

• shared finding schema v2 with info severity, detectionMethod, falsePositiveRisk, remediationEffort, complianceMapping, and evidence fields
• deterministic per-edit warnings, background diff review, and checkpoint review
• repository-wide audit mode (pattern scanner + entropy scanner) with SARIF, summary, markdown, and compliance report output
• baseline mode for delta comparison (new/resolved/unchanged findings)
• compliance mapping to BIO2, NORA, ISO 27001, NIST CSF, and OWASP Top 10
• suppression governance with expiry, ownership, path scoping, and repository-scoped audit suppressions
• JSONL audit logging
• a runnable CLI with review, audit, and baseline subcommands
• OpenCode and Codex adapters
• CI for lint and tests (208 tests passing)

It does not claim security guarantees. It is a review assistant with explicit trust boundaries.

Design Goals

• Preserve a three-layer review model:
  • deterministic per-edit warnings,
  • background end-of-turn diff review,
  • deeper commit and push review.
• Keep the real logic in a shared core.
• Support local-first operation.
• Keep repo policy additive only.
• Emit structured evidence.

Repo Layout

• src/core/ shared review logic (review, audit, baseline, entropy scanner, compliance)
• src/adapters/opencode/ OpenCode integration scaffold
• src/adapters/codex/ Codex integration scaffold
• .claude-plugin/, hooks/, bin/ host plugin packaging
• .github/workflows/ CI
• schemas/ JSON Schemas (finding v2, config)
• examples/ sample additive policy and custom patterns
• docs/ architecture, parity spec, threat model
• tests/ node:test coverage (208 tests)
• tests/corpus/audit/ audit mode fixture files

Usage

Review Mode (default)

node ./src/cli.js --diff-file <file> --changed-files <paths> --format sarif

Audit Mode

Repository-wide security audit with pattern and entropy scanning:

# Full audit (JSON output)
node ./src/cli.js audit --repo-root .

# Audit with compliance mapping (markdown)
node ./src/cli.js audit --format compliance-markdown --repo-root .

# Audit with compliance mapping (JSON)
node ./src/cli.js audit --format compliance-json --repo-root .

# Audit including git history
node ./src/cli.js audit --include-history --repo-root .

# Legacy flag (deprecated, use subcommand instead)
node ./src/cli.js --audit --format summary

Audit output formats:

Format	Flag	Description
JSON	--format json	Full findings with metadata (default)
Summary	--format summary	Severity counts
Markdown	--format markdown	Human-readable report
SARIF	--format sarif	SARIF 2.1.0 for GitHub Advanced Security
Compliance Markdown	--format compliance-markdown	Findings grouped by framework and control
Compliance JSON	--format compliance-json	Structured compliance report

Baseline Mode

Create and compare against a security baseline:

# Write a baseline snapshot
node ./src/cli.js baseline --write-baseline --repo-root .

# Audit against a baseline (exit 1 for new critical/high findings, exit 2 for missing baseline)
node ./src/cli.js audit --baseline .security-baseline.json --repo-root .

Entropy Scanner

The audit mode automatically runs entropy scanning alongside pattern matching. High-entropy strings (>4.5 bits/char by default) that don't match known secret prefixes are flagged with detectionMethod: "entropy" and elevated falsePositiveRisk in test directories.

Configure via security-review.config.json:

{
  "scanners": {
    "entropy": true,
    "entropyThreshold": 4.5
  }
}

Compliance Mapping

Each finding maps to regulatory frameworks: BIO2, NORA, ISO 27001, NIST CSF, OWASP Top 10. Filter by profile:

{
  "compliance": {
    "profiles": ["BIO2", "NORA"],
    "evidenceLevel": "detailed"
  }
}

CLI Help

node ./src/cli.js --help
node ./src/cli.js audit --help
node ./src/cli.js baseline --help

Suppress false positives with owner, justification, and expiry:

{
  "suppressions": [
    {
      "ruleId": "no-hardcoded-secrets",
      "pathRegex": "test/fixtures/.*",
      "owner": "[email protected]",
      "justification": "Test fixture mock secrets",
      "expiresOn": "2025-12-31",
      "scope": "file"
    }
  ]
}

Repository-scoped suppressions only apply in audit mode:

{
  "ruleId": "no-internal-ips",
  "owner": "[email protected]",
  "justification": "Accepted: internal monitoring endpoints",
  "expiresOn": "2025-12-31",
  "scope": "repository"
}

Trust Boundaries