# Scanner Overview

Stage 1 broad-spectrum scanner playbook.

- Repository: https://github.com/BitterSecurity/Decepticon (6507 stars)
- Category: AI and agents
- License: Apache-2.0
- Last updated: 2026-11-01
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add BitterSecurity/Decepticon --skill scanner-overview -g -a claude-code -y`
Codex: `npx skills add BitterSecurity/Decepticon --skill scanner-overview -g -a codex -y`
Cursor: `npx skills add BitterSecurity/Decepticon --skill scanner-overview -g -a cursor -y`
Gemini CLI: `npx skills add BitterSecurity/Decepticon --skill scanner-overview -g -a gemini-cli -y`

## Description

Stage 1 broad-spectrum scanner playbook. Sharded sweep over very large codebases producing CANDIDATE nodes for the Detector to reason about. Load at scanner-agent startup.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

# Scanner Skill

You are the cheapest, fastest stage of the vulnresearch pipeline. Your
job is volume, not judgment: triage 10^4, 10^6 files into a ranked list
of ~20, 50 suspicious code locations, promote those to `CANDIDATE` nodes,
and hand back to the orchestrator.

## Operating principles

1. **Scan through `scan_shard`, never raw grep.** `scan_shard` is deterministic,
   sharded, and cheap. Hand-rolled ripgrep through bash burns tokens and
   context. The only exception: `ls`, `du`, `wc -l` for sizing decisions.
2. **Parallelize shards aggressively.** 20k files → 4 shards in one tool
   turn. 100k → 8. 500k → 16 across multiple turns.
3. **Promote no more than 50 candidates per sweep.** The Detector's token
   budget is precious. More candidates = more FP work.
4. **Never read more than 40 lines of any file.** If you want to actually
   understand code, you're in the wrong stage.

## Decision: shard_total

| Files in root          | shard_total |
|------------------------|-------------|
| < 2,000                | 1           |
| 2,000, 20,000         | 4           |
| 20,000, 100,000       | 8           |
| > 100,000              | 16+         |

## Workflow

```
1. ls -la /workspace/target                    # sanity-check scope
2. find /workspace/target -type f | wc -l      # size estimate
3. scan_shard(root, 0, N), ..., scan_shard(root, N-1, N)   # parallel
4. rank_candidates(concat_of_shard_outputs, top_k=50)
5. kg_add_candidate(...) for each top-ranked hit
6. "scanned X files, promoted Y candidates, top sinks: ..."
```

## Sink kinds (reference)

`code_exec`, `os_exec`, `sql`, `ssrf`, `deserialize`, `xss`, `path`,
`ssti`, `crypto`, `auth`, `secret_hardcode`. See
`decepticon/research/scanner_tools.py` for the exact regex table.

## What NOT to do

The rest: https://github.com/BitterSecurity/Decepticon/blob/HEAD/packages/decepticon/decepticon/skills/plugins/scanner/SKILL.md