# Security Quality Assess

> Automated security vulnerability scanning for Python and JavaScript/TypeScript codebases. Detects OWASP Top 10 vulnerabilities, hardcoded secrets, injection risks, and known CVEs with actionable remediation guidance. This is the whole-codebase automated scan; reviewing a specific PR, branch diff, or auth change for security issues is /security-review or the security-auditor agent instead.

- Skill: `artsmc-claude-dev-agents/security-quality-assess` (Agent Skill, multi-file: 54 files)
- Install (CLI): `npx skillmds@latest add artsmc-claude-dev-agents/security-quality-assess`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc-claude-dev-agents/security-quality-assess/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: artsmc (https://skillmd.com/u/artsmc-claude-dev-agents)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc-claude-dev-agents/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

```bash
# 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:

```bash
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
```bash
# 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
```bash
# 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
```bash
# 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