Security Quality Assess

Security Quality Assessment Skill

Comprehensive static security analysis that automatically scans codebases to detect vulnerabilities across OWASP Top 10 (2021) categories.

Use this skill to identify security vulnerabilities early in development, maintain security compliance, and receive actionable remediation guidance for detected issues.

Usage

# Scan current project
/security-assess .

# Scan specific directory
/security-assess /path/to/project

# Save report to file
/security-assess . --output security-report.md

# Skip network dependency scanning (faster)
/security-assess . --skip-osv

# Verbose logging for debugging
/security-assess . --verbose

What This Skill Does

Performs comprehensive security analysis to answer:

• What security vulnerabilities exist in my codebase?
• Are there hardcoded secrets or credentials?
• Which dependencies have known CVEs?
• What's my overall security risk score?
• How do I fix the identified issues?

Detection Coverage

Covers OWASP Top 10 (2021) categories A01-A07: access control, cryptographic failures, injection, insecure design, misconfiguration, vulnerable components (CVEs), and authentication failures. Read references/detection-coverage.md for the full per-category list of detected patterns when you need to know exactly what is flagged.

Severity Levels

Findings are prioritized for action:

• CRITICAL - Immediate action required (hardcoded credentials, code injection, known CVEs with CVSS 9.0+)
• HIGH - Fix within 1 sprint (SQL injection, missing auth, weak crypto, CVSS 7.0-8.9)
• MEDIUM - Plan remediation (insecure configs, minor misconfigurations, CVSS 4.0-6.9)
• LOW - Nice to fix (code quality improvements, CVSS 0.1-3.9)

Exit Codes

The tool uses exit codes for CI/CD integration:

• 0 - Clean (no CRITICAL or HIGH findings)
• 1 - Issues found (CRITICAL or HIGH findings detected)
• 2 - Fatal error (analysis failed to complete)

Suppression System

Suppress false positives with an audit trail via .security-suppress.json (entries support expiration dates and approver fields). Read references/configuration.md for the file format, matching precedence, and expiration rules when suppressing findings.

Workflow verify (diverse-lens false-positive reduction)

scripts/assess.py is a deterministic pattern-matcher — it has no way to tell a real vulnerability from a docstring that happens to mention one, or a sanitized call that happens to match a risky API name. For a lower-false-positive report, wrap its output in the diverse-lens verify graph: workflows/security-quality-assess-verify.js, invoked via Workflow({ scriptPath: '~/.claude/workflows/security-quality-assess-verify.js' }) (never by name — see docs/graph-orchestration.md §6). It does not re-scan anything; it takes assess.py's own findings as input, one grounding agent per file re-reads the real code, then three distinct-lens verifiers (correctness / security / reproduces) each try to REFUTE every finding, defaulting to refuted under uncertainty. A finding reaches the report only on majority non-refutation (FRS FR-14).

Because assess.py has no --format json flag, obtain the findings array (reusing assess.py's own internal pipeline, not a reimplementation of it) with:

cd skills/security-quality-assess && python3 -c "
import sys, json; sys.path.insert(0, '.')
from pathlib import Path
from scripts.assess import parse_all_files, run_analyzers, handle_suppressions, build_assessment_result
from lib.discovery import discover_source_files, discover_lockfiles, parse_gitignore
p = Path('<project_path>').resolve()
gi = parse_gitignore(p); errors = []
src = discover_source_files(p, gi); lock = discover_lockfiles(p)
parsed = parse_all_files(src, lock, p, errors=errors)
findings = run_analyzers(parsed, skip_osv=True, errors=errors)
filtered, suppressed = handle_suppressions(findings, p, None)
result = build_assessment_result(project_path=p, files_analyzed=len(src), scan_duration=0.0, findings=filtered, suppressed_count=suppressed, errors=errors)
print(json.dumps([f.to_dict() for f in result.findings]))
"

then pass that array as args.findings (plus repo_root and project_path) to the workflow.

When to use the plain analyzer vs the verify graph:

• Plain assess.py — fast, deterministic, CI-gate-friendly (--skip-osv, exit codes). Use it for routine scans, pre-commit checks, and anywhere a human will triage the report anyway.
• The verify graph — costs one grounding agent per file plus 3 verifier agents per finding (bounded by args.max_findings, default 15, to stay within the ~15-agent session guideline; anything excluded by the bound is disclosed, never silently dropped, per FRS FR-17). Use it when the finding set is going into an automated gate or a report a human will act on without re-checking each line themselves, and false positives are costly to chase down.

Measured on the skill's own fixtures (tests/fixtures/, ground-truthed by expected_findings.json): the raw analyzer produced 21 findings across the four pattern-detection fixtures (secrets/auth/xss/injection) plus 34 across lockfiles/package-lock.json. The verify pass removed 3 of the 21 (a docstring mis-match and a DOMPurify-sanitized call, both refuted 3/3 by all lenses) and 1 of the 34 (a duplicate CVE re-listing, refuted 2/3), with every finding present in expected_findings.json retained. Full methodology and numbers: ~/.claude/job-queue/feature-graph-orchestration/docs/planning/task-updates/task-15-diverse-lens-verify.md.

Common Workflows

Pre-Commit Security Check

# Run scan before committing
/security-assess . --output report.md

# Check exit code
if [ $? -eq 0 ]; then
  git commit -m "Feature complete"
else
  echo "Security issues found - review report.md"
fi

CI/CD Integration

# Run in pipeline with verbose logging
/security-assess . --verbose --output security-report.md

# Fail build on critical/high findings
exit_code=$?
if [ $exit_code -eq 1 ]; then
  echo "Security vulnerabilities block merge"
  exit 1
fi

Fast Local Development Scan

# Skip dependency scanning for faster analysis
/security-assess . --skip-osv --output quick-scan.md

Report Output

The markdown report includes:

1. Executive Summary - Risk score, finding counts by severity
2. Risk Breakdown - Visual distribution of findings
3. OWASP Top 10 Coverage - Findings mapped to categories
4. Detailed Findings - Each issue with:
   • File path and line number
   • Code snippet with context
   • OWASP category and CWE reference
   • Specific remediation guidance
5. Suppressions Summary - Count of suppressed and expired suppressions

Limitations

Language Support:

• Currently supports Python (.py) and JavaScript/TypeScript (.js, .ts, .jsx, .tsx)
• More languages planned for future releases

False Positives:

• Static analysis may flag legitimate code patterns
• Use suppression system to manage false positives
• Tool automatically excludes common test directories

Network Dependency:

• CVE detection requires OSV API access
• Use --skip-osv flag when offline
• Results cached for 24 hours in ~/.cache/claude-security/osv/

Performance:

• Typical: ~10,000 LOC/second
• OSV API queries add 2-5 seconds per scan
• Large codebases (>100K LOC) may take 30+ seconds

Technical Details

• Zero Dependencies - Pure Python 3.8+ standard library
• Fast Performance - Scans 12K LOC in ~0.88 seconds
• Smart Defaults - Respects .gitignore, excludes test files
• CVE Database - Queries OSV.dev API for known vulnerabilities
• Caching - 24-hour cache for dependency vulnerability data

Configuration Options

Full CLI flag reference (--output, --config, --skip-osv, --verbose, --version, --help) is in references/configuration.md — read it when customizing a scan invocation.

Quality Metrics

This skill provides:

• Risk Score (0-100) - Weighted by severity
• Finding Counts - Breakdown by CRITICAL/HIGH/MEDIUM/LOW
• OWASP Coverage - Findings mapped to Top 10 categories
• Security Posture - Overall assessment with actionable recommendations

Version: 1.0.0 Status: Production Ready Languages Supported: Python, JavaScript, TypeScript Last Updated: 2026-02-08