A Claude Code skill bundle for bug hunting and external red-team work - 82 skills, 15 slash commands, 681 disclosed-report patterns curated across 24 core vulnerability classes, plus enterprise identity + infrastructure attack matrices.
Python ai-securityanthropicapplication-securitybug-bountybugbountybugcrowdclaudeclaude-codeclaude-skillsethical-hackinghackeroneoffensive-securitypentestingred-teamsecurity-toolsweb-security
#!/usr/bin/env python3
"""
lint_skills.py — quality + safety gate for claude-bughunter skills.
Enforces the rules documented in CONTRIBUTING.md and the repo's hard rule that
NO real client/engagement identifiers ever land in the public tree.
Checks per skills/<name>/SKILL.md:
STRUCTURE (errors)
- frontmatter block present (between the first two `---` lines)
- `name` present, matches ^[a-z0-9-]+$, and equals the directory name
- `description` present and <= 1024 chars
- body (everything after frontmatter) <= 500 lines
SAFETY (errors)
- client-identifier denylist: hashes every 1- and 2-word shingle of the file
and compares against scripts/.identifier-denylist.sha256 (+ optional
.identifier-denylist.local). Plaintext names never live in the repo.
- real-secret scan: AWS keys, private-key blocks, JWTs, Slack/Google tokens.
Documentation patterns (regexes, AWS EXAMPLE tokens) are allowlisted so the
secret-catalog skills don't trip it.
Exit code 0 = clean, 1 = at least one error. Warnings never fail the build.
Stdlib only — no pip install needed in CI.
Usage:
python3 scripts/lint_skills.py # lint all skills
python3 scripts/lint_skills.py skills/hunt-xss # lint specific dirs
"""
import hashlib
import os
import re
import sys
REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
SKILLS_DIR = os.path.join(REPO, "skills")
SCRIPTS_DIR = os.path.join(REPO, "scripts")
NAME_RE = re.compile(r"^[a-z0-9-]+$")
MAX_DESC = 1024
MAX_BODY_LINES = 500
# Grounding enforcement. Every skill must declare `sources:`; hunt-* skills (built
# from disclosed reports) must also declare an integer `report_count:` (0 is fine
# when `sources:` justifies it — e.g. a pattern library or research-derived skill).
# Phase 4a shipped this as WARNINGS while the backfill landed; now enforced as errors.
GROUNDING_STRICT = True
# --- real-secret patterns (kept tight to avoid flagging documented regexes) ---
SECRET_PATTERNS = [
("AWS access key", re.compile(r"\bAKIA[0-9A-Z]{16}\b")),
("Private key block", re.compile(r"-----BEGIN (?:RSA |EC |OPENSSH |DSA |PGP )?PRIVATE KEY-----")),
("JWT", re.compile(r"\beyJ[A-Za-z0-9_-]{8,}\.eyJ[A-Za-z0-9_-]{8,}\.[A-Za-z0-9_-]{8,}\b")),
("Slack token", re.compile(r"\bxox[baprs]-[0-9A-Za-z-]{10,}\b")),
("Google API key", re.compile(r"\bAIza[0-9A-Za-z_-]{35}\b")),
("GitHub PAT", re.compile(r"\bghp_[0-9A-Za-z]{36}\b")),
]
# Tokens that are public documentation/examples, not real secrets.
# `\.\.\.` covers placeholder blocks like "-----BEGIN PRIVATE KEY-----..." in docs.
SECRET_ALLOW = re.compile(
r"AKIAIOSFODNN7EXAMPLE|EXAMPLE|wJalrXUtnFEMI|\[0-9A-Z\]|\{1[06]\}|<[^>]+>|\.\.\."
)
# Intentional kitchen-sink router/aggregator skills whose descriptions deliberately
# exceed the per-skill limit (they route to everything). Over-length is a warning,
# not an error, for these. Do NOT add new skills here — write focused descriptions.
DESC_LIMIT_GRANDFATHERED = {"bug-bounty", "bb-local-toolkit", "osint-methodology"}
WORD_RE = re.compile(r"[a-z0-9]+")
def load_denylist():
"""Return a set of sha256 hex digests of banned identifiers."""
hashes = set()
sha_file = os.path.join(SCRIPTS_DIR, ".identifier-denylist.sha256")
if os.path.exists(sha_file):
with open(sha_file, encoding="utf-8") as fh:
for line in fh:
line = line.strip()
if line and not line.startswith("#"):
hashes.add(line.lower())
# Optional gitignored plaintext override for maintainer convenience.
local = os.path.join(SCRIPTS_DIR, ".identifier-denylist.local")
if os.path.exists(local):
with open(local, encoding="utf-8") as fh:
for line in fh:
name = " ".join(line.strip().lower().split())
if name and not name.startswith("#"):
hashes.add(hashlib.sha256(name.encode()).hexdigest())
return hashes
def shingles(text):
"""Yield normalized 1- and 2-word shingles from text."""
words = WORD_RE.findall(text.lower())
for i, w in enumerate(words):
yield w
if i + 1 < len(words):
yield w + " " + words[i + 1]
def split_frontmatter(raw):
"""Return (frontmatter_dict, body_text, error_or_None)."""
if not raw.startswith("---"):
return {}, raw, "no frontmatter block (file must start with '---')"
parts = raw.split("\n")
# find closing --- after line 0
close = None
for i in range(1, len(parts)):
if parts[i].strip() == "---":
close = i
break
if close is None:
return {}, raw, "frontmatter opened with '---' but never closed"
fm = {}
for line in parts[1:close]:
if not line.strip() or line.lstrip().startswith("#"):
continue
m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", line)
if m:
fm[m.group(1)] = m.group(2).strip()
body = "\n".join(parts[close + 1:])
return fm, body, None
def yaml_safety_errors(name, raw):
"""Catch frontmatter a STRICT YAML parser (e.g. Codex) rejects but our lenient
regex parser accepts — chiefly an unquoted value containing ': ' (colon-space),
which YAML reads as a nested mapping. This is the hunt-ntlm-info bug class."""
errs = []
if not raw.startswith("---"):
return errs
lines = raw.split("\n")
for i in range(1, len(lines)):
if lines[i].strip() == "---":
break
m = re.match(r"^([A-Za-z0-9_-]+):\s*(.*)$", lines[i])
if not m or not m.group(2):
continue
val = m.group(2)
quoted = len(val) >= 2 and val[0] == val[-1] and val[0] in "\"'"
if not quoted and ": " in val:
errs.append(f"{name}: frontmatter `{m.group(1)}` is unquoted and contains ': ' — "
f"wrap the value in double quotes (strict YAML parsers like Codex reject it)")
return errs
def lint_skill(skill_dir, denylist):
errors, warnings = [], []
name = os.path.basename(skill_dir.rstrip("/"))
path = os.path.join(skill_dir, "SKILL.md")
if not os.path.isfile(path):
return [f"{name}: missing SKILL.md"], []
with open(path, encoding="utf-8") as fh:
raw = fh.read()
fm, body, fm_err = split_frontmatter(raw)
if fm_err:
errors.append(f"{name}: {fm_err}")
errors += yaml_safety_errors(name, raw)
# name
fn = fm.get("name", "")
if not fn:
errors.append(f"{name}: frontmatter missing `name`")
else:
if not NAME_RE.match(fn):
errors.append(f"{name}: `name` '{fn}' must match ^[a-z0-9-]+$")
if fn != name:
errors.append(f"{name}: `name` '{fn}' != directory '{name}'")
# description
desc = fm.get("description", "")
if not desc:
errors.append(f"{name}: frontmatter missing `description`")
elif len(desc) > MAX_DESC:
msg = (f"{name}: description {len(desc)} chars > {MAX_DESC} limit "
f"(Codex rejects >1024; install.sh --agents auto-truncates the Codex copy)")
(warnings if name in DESC_LIMIT_GRANDFATHERED else errors).append(msg)
elif len(desc) < 40:
warnings.append(f"{name}: description very short ({len(desc)} chars) — weak trigger surface")
# body length
body_lines = len(body.splitlines())
if body_lines > MAX_BODY_LINES:
warnings.append(f"{name}: body {body_lines} lines > {MAX_BODY_LINES} guideline (use references/ subfolder)")
# grounding: every skill declares `sources:`; hunt-* also declares report_count.
grounding = errors if GROUNDING_STRICT else warnings
if not fm.get("sources", "").strip():
grounding.append(f"{name}: missing `sources:` — declare grounding provenance in frontmatter")
if name.startswith("hunt-"):
rc = fm.get("report_count")
if rc is None:
grounding.append(f"{name}: hunt-* skill missing `report_count:` (use 0 if not a counted-report corpus)")
elif not re.fullmatch(r"\d+", rc.strip()):
grounding.append(f"{name}: `report_count: {rc}` must be a non-negative integer")
# client-identifier denylist
if denylist:
hit = set()
for sh in shingles(raw):
if hashlib.sha256(sh.encode()).hexdigest() in denylist:
hit.add(sh)
if hit:
errors.append(
f"{name}: CLIENT-IDENTIFIER MATCH — {len(hit)} banned shingle(s). "
f"Remove client/engagement identifiers before committing."
)
# real-secret scan
for lineno, line in enumerate(raw.splitlines(), 1):
for label, pat in SECRET_PATTERNS:
for m in pat.finditer(line):
snippet = m.group(0)
window = line[max(0, m.start() - 8): m.end() + 8]
if SECRET_ALLOW.search(window) or SECRET_ALLOW.search(snippet):
continue
errors.append(f"{name}:{lineno}: possible {label} leaked — '{snippet[:24]}...'")
return errors, warnings
def main(argv):
denylist = load_denylist()
if argv:
targets = [a if os.path.isabs(a) else os.path.join(REPO, a) for a in argv]
else:
targets = [os.path.join(SKILLS_DIR, d) for d in sorted(os.listdir(SKILLS_DIR))
if os.path.isdir(os.path.join(SKILLS_DIR, d))]
all_errors, all_warnings = [], []
for t in targets:
e, w = lint_skill(t, denylist)
all_errors += e
all_warnings += w
for w in all_warnings:
print(f"::warning:: {w}" if os.environ.get("GITHUB_ACTIONS") else f"WARN {w}")
for e in all_errors:
print(f"::error:: {e}" if os.environ.get("GITHUB_ACTIONS") else f"ERROR {e}")
n = len(targets)
print(f"\nLinted {n} skill(s): {len(all_errors)} error(s), {len(all_warnings)} warning(s).")
if not denylist:
print("NOTE: no client-identifier denylist loaded (scripts/.identifier-denylist.sha256 missing).")
return 1 if all_errors else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))