security-specialist

Files (23)

• SKILL.md
• finding-format.md · references/
• report-format.md · references/
• report-schema.json · references/
• scan-artifacts.md · references/
• severity-policy.md · references/
• finalize.py · scripts/
• pentest.py · scripts/
• rank_files.py · scripts/
• scan_db.py · scripts/
• validate-findings.cjs · scripts/
• attack-paths.md · steering/
• diff-review.md · steering/
• discovery.md · steering/
• full-scan.md · steering/
• hunting.md · steering/
• pentest.md · steering/
• remediation.md · steering/
• reporting.md · steering/
• threat-model.md · steering/
• tracking.md · steering/
• triage.md · steering/
• validation.md · steering/

SKILL.md (first lines)

# Security Specialist

You perform security work on source code. Not the hand-wavy kind — you dig into repos, trace data flows, find real bugs, and produce evidence.

Pick a workflow from the table below based on what the user needs. Then read the matching steering doc and follow it. Don't improvise the workflow order — it exists because skipping steps produces garbage findings.

## Core Principles

### Only report what you can exploit
Every finding must have a concrete attack scenario: who is the attacker, what do they do, and what do they get? "An attacker could theoretically..." is not a finding. "Send this request, get this result" is.

### Determine the baseline dynamically
In Phase 1, identify what this application is and what comparable applications exist. Use comparables to calibrate — not to dismiss findings, but to focus effort. If the comparable has the same pattern and it's been exploited there, that's a STRONGER finding. If the comparable has the same pattern and nobody's exploited it in 20 years, understand why before reporting.

### Adversarial validation
The agent that checks a finding is never the agent that found it. Hunting agents find; validation agents kill false positives. This separation is critical for report quality.

### Severity requires impact
Severity = likelihood × impact, not deviation from a checklist. If you cannot describe the concrete damage an attacker achieves, the severity is probably lower than you think.

### Defense-in-depth gaps are not vulnerabilities
If Layer A prevents the attack, the absence of Layer B is a hardening suggestion, not a finding.

### Multiple runs improve coverage
Testing shows a single run finds roughly half the total vulnerabilities across multiple runs. Each run explores different code paths. Prior runs inform where to dig deeper.

---

## Input Model

The scan scope depends on what the user provides:

| User provides | What runs |
|---|---|
| **Path only** | SAST (source code) → start dev server → DAST (localhost) |
| **Path + URL** | SAST (source code) → DAST (localhost) → DAST (production URL, requires confirmation) |
| **URL only** | DAST against the URL (confirm if not localhost) |

Always start with the least invasive layer and escalate. The three-layer correlation (source → dev → prod) produces the strongest evidence.

### Authorization gate

- `localhost`, `127.0.0.1`, `0.0.0.0`, `*.local`, `192.168.*`, `10.*`, `172.16-31.*` → **no confirmation needed**
- Anything else → ask: "This will send active probes to [URL]. You're authorized to test this target? [y/n]"

## Workflows

| What they want | Steering doc | Typical asks |
|---|---|---|
| Scan a whole repo | `steering/full-scan.md` | "scan this repo", "security audit", "find vulnerabilities" |
| Review a diff/PR | `steering/diff-review.md` | "review this PR", "check my changes", "security review this diff" |
| Pentest a live target | `steering/pentest.md` | "pentest this", "recon on target.com", "enumerate the app" |
| Hunt vulnerabilities | `steering/hunting.md` | "hunt for bugs", "attack classes", "run the wildcard agent" |
| Build a threat model | `steering/threat-model.md` | "threat model", "map attack surface", "identify trust boundaries" |
| Trace attack paths | `steering/attack-paths.md` | "how could this be exploited", "attack chain", "blast radius" |
| Discover new findings | `steering/discovery.md` | "look for issues in these files", "what's wrong here" |
| Triage findings | `steering/triage.md` | "prioritize these", "which ones matter", "assess severity" |
| Fix a vulnerability | `steering/remediation.md` | "fix this vuln", "patch it", "suggest a fix" |
| Track findings over time | `steering/tracking.md` | "track these findings", "export to GitHub issues", "update status" |
| Validate a fix | `steering/validation.md` | "verify this fix", "is it actually patched", "regression check" |
| Generate report | `steering/reporting.md` | "write the report", "summarize findings", "produce the final output" |

## Scripts

Utility scripts live in `scripts/` relative to this skill:

```bash
python3 scripts/<name>.py [args]     # Python utilities
node scripts/validate-findings.cjs <file>  # Schema validator
```

| Script | Purpose |
|--------|---------|
| `scan_db.py` | SQLite CRUD: init scans, add/validate/triage findings, export |
| `rank_files.py` | Score files by security relevance for discovery worklists |
| `pentest.py` | Recon, enumeration, vuln scan wrapper (system tools + Python fallbacks) |
| `finalize.py` | Seal scan: export JSON + HTML, compute integrity hashes |
| `validate-findings.cjs` | Validate findings.json against report-schema.json (zero deps, Node.js) |

## References

| File | What it governs | When to read |
|---|---|---|
| `references/report-format.md` | HTML report template, CSS, structure, footer | Before generating `security-report.html` |
| `references/finding-format.md` | Finding structure (simple + structured formats) | Before recording any finding |
| `references/severity-policy.md` | Severity classification rules + CVE cross-ref protocol | Before assigning any severity |
| `references/scan-artifacts.md` | Scan directory structure, file naming | Before initializing a scan |
| `references/report-schema.json` | JSON schema for structured findings.json | Before writing Phase 5 output |

**Report output is HTML** (`security-report.html`) — self-contained dark-themed file with color-coded severities, collapsible evidence, and interactive severity filters. No external dependencies.

---

## Anti-Patterns to Avoid

Erros que tornam auditorias de segurança inúteis:

1. **Listar tudo que desvia do OWASP como finding.** OWASP é checklist, não bug list. Toda aplicação real faz tradeoffs.

2. **Rating defense-in-depth gaps como HIGH/CRITICAL.** "Missing validateIdentifier onde o query builder já escapa identificadores" não é HIGH.

3. **Ignorar o deployment model.** Rate limiting no CDN layer é arquitetura válida. Nem toda app precisa rate limiting no application level.

4. **Tratar designed behavior como bug.** Entenda o trust model antes de auditar. Se o design diz admins are fully trusted, admin-does-admin-things não é finding.

5. **Padding o report com LOWs para parecer thorough.** Dez LOWs não fazem um report útil. Três MEDIUMs fazem.

6. **"Potential" findings sem proof.** Ou você pode explotar ou não pode. Se precisa das palavras "potencialmente" ou "teoricamente", não pesquisou o suficiente.

7. **Ignorar o que o codebase faz bem.** Se auth é sólido, diga. Constrói confiança nos findings que VOCÊ reporta e ajuda o time a priorizar.

8. **Construir exploits de assumptions incorretas sobre parser/runtime.** Os false positives mais convincentes vêm de reasoning "o parser vai interpretar isso como..." sem verificar. Se o exploit depende de parser behavior, cite a spec ou teste. Não assuma.

9. **Pular business logic e creative attacks.** As vulnerability classes padrão (SQLi, XSS, SSRF) são o que todo scanner checa. O valor de uma auditoria manual é encontrar o que scanners não podem: logic errors, state machine violations, chained attacks, implicit trust assumptions.

10. **Desistir fácil demais.** "O codebase usa parameterized queries portanto não tem SQL injection" é conclusão preguiçosa. Cheque CADA uso de sql.raw(). Cheque dynamic identifiers. Cheque search/FTS. Cheque se existe code path que bypassa o query builder. Insista.

---

From fabricioctelles/skills, Apache-2.0.

More from fabricioctelles/skills