Skip to content
19 changes: 19 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -49,6 +49,25 @@ versioning is loosely [SemVer](https://semver.org/) at the bundle level.
remain Claude-Code-only. New guide: `docs/multi-harness.md`.

### Fixed
- **`cbh triage` 7-Question Gate — three false-verdict paths** (built in-house, reporters credited):
Q1 matched a bare method word anywhere in the text, so prose like `target application`
(contains `get `) or `input validation` passed Q1 with no request — Q1 now requires a method
followed by a path or URL (or `curl` / `HTTP/1.1`) (reported by @dajiaohuang, #209); Q7's
never-submit list caught `click-jacking` but not `clickjacking` (reported by @Ethereal49, #197);
Q3 answered YES on scope wording even when the finding itself said *out of scope* / *unverified*
— a scope/asset line carrying a negation no longer counts as in-scope evidence (reported by
@Ethereal49, #197).
- **`cbh report` dropped frontmatter behind a UTF-8 BOM** — a BOM written by some Windows editors
sat before the `---` fence, so severity/asset fell back to defaults. `parse_finding_metadata`
now strips a leading BOM at the shared chokepoint. Reported by @jazzpher (#200).
- **`cbh` / `setup_harness_mcp.py` crashed on non-UTF-8 Windows consoles** — the gate glyphs
(✓/✗/→/—) raised `UnicodeEncodeError` under cp1252. Both entrypoints now reconfigure stdout/stderr
to UTF-8, matching `engine/engine.py`. Reported by @Sahilkumar-r (#180).
- **`h1_reference.py --program` returned nothing** — `CompleteHacktivityReportIndex` no longer
accepts `terms: {team_id: ...}`; switched to `query_string: "team_handle:<handle>"`, which filters
correctly and composes with `--top-voted`/`--top-bounty`. Lookup progress moved to stderr so
`--json` stdout stays pipeable. Two independent reports converged here: @roonnnnyyyyyy (#206) and
@flipcyde101 (#202).
- `hunt-clickjacking`, `hunt-html-injection`: quoted the `description` — an unquoted `: ` (`Targets:`,
`surfaces:`) broke strict YAML / Codex. Also genericized lab/harness-specific language in the new
skills for cross-harness portability.
Expand Down
62 changes: 59 additions & 3 deletions cbh/cli.py
Original file line number Diff line number Diff line change
Expand Up @@ -638,9 +638,21 @@ def cmd_classify(args: argparse.Namespace) -> int:
# ============================================================
# triage — run the 7-Question Gate against a finding markdown
# ============================================================
# Q1 asks for a real request, so a bare method word only counts when a
# request-target (a path or URL) follows it. Plain substrings like "GET " used
# to match inside prose ("tarGET application", "inPUT validation"), letting an
# untested finding answer Q1 YES. The separator class allows the markdown a PoC
# is usually written in — backticks and bold/italic around the method or path
# (`GET /x`, **GET** /x, GET `/x`).
# ponytail: heuristic ceiling — prose like "an attacker can get /admin" still
# reads as a request. Requiring HTTP/ or a scheme after the path would reject
# the common bare "GET /path?x=1" PoC (see test_lowercase_request_line), so a
# method+path match is the accepted floor; the human reads the verdict.
_REQUEST_LINE = re.compile(r"\b(?:get|post|put|patch|delete)[ \t`*_]+(?:/|https?://)")

TRIAGE_QUESTIONS = [
("Q1", "Can an attacker use this RIGHT NOW with a real HTTP request?",
["curl ", "POST ", "GET ", "HTTP/1.1", "PUT ", "DELETE ", "PATCH "]),
["curl ", "http/1.1", _REQUEST_LINE]),
("Q2", "Is the impact on the program's accepted-impact list?",
["impact:", "severity:", "p1", "p2", "p3", "p4", "critical", "high", "medium", "low"]),
("Q3", "Is the asset in scope?",
Expand All @@ -653,9 +665,40 @@ def cmd_classify(args: argparse.Namespace) -> int:
["leaked", "exfiltrated", "rce", "data:", "credential", "session-id", "cookie:",
"admin email", "production", "oob callback", "interactsh"]),
("Q7", "Is this not on the never-submit list?",
["self-xss", "rate-limit only", "click-jacking", "csrf on logout", "missing security headers"]),
["self-xss", "rate-limit only", "click-jacking", "clickjacking",
"csrf on logout", "missing security headers"]),
]

# Q3 disqualifiers: scope/asset wording is not affirmative evidence when the
# finding itself disavows the asset. Two kinds of disavowal:
# - STRONG phrases ("out of scope", "excluded from scope") are unambiguous on
# any line, including prose ("this asset is out of scope").
# - WEAK words ("unknown", "unclear", "maybe") only disavow when they sit on a
# scope/asset/target line — otherwise "Impact: unclear scope of exposure" or
# "previously unknown" would wrongly kill an in-scope finding.
# Hyphens are normalized to spaces first, so "out-of-scope" matches "out of scope".
_Q3_STRONG = ("out of scope", "not in scope", "outside scope", "excluded from scope")
_Q3_WEAK = ("not verified", "unverified", "unknown", "possibly", "maybe", "unclear")
_Q3_SCOPE_KEYS = ("scope", "asset", "target", "affected asset", "in scope", "out of scope")


def _signal_hit(signal, text: str) -> bool:
"""One triage signal: a compiled pattern searches, a string is a substring."""
if isinstance(signal, re.Pattern):
return signal.search(text) is not None
return signal.lower() in text


def _q3_scope_negated(text: str) -> bool:
for ln in text.splitlines():
norm = ln.replace("-", " ").lower()
if any(phrase in norm for phrase in _Q3_STRONG):
return True
key = norm.split(":", 1)[0].strip("*`•# ").strip()
if key in _Q3_SCOPE_KEYS and any(w in norm for w in _Q3_WEAK):
return True
return False


def cmd_triage(args: argparse.Namespace) -> int:
finding_path = Path(args.finding)
Expand All @@ -671,7 +714,9 @@ def cmd_triage(args: argparse.Namespace) -> int:
answers = []
for qid, question, signals in TRIAGE_QUESTIONS:
# Q7 is INVERTED: presence of a "never-submit" signal = answer is "NO" (kill)
hit = any(s.lower() in text for s in signals)
hit = any(_signal_hit(s, text) for s in signals)
if qid == "Q3" and hit and _q3_scope_negated(text):
hit = False # scope words present, but the finding disavows the scope
if qid == "Q7":
answer = "NO — finding matches never-submit category" if hit else "YES"
ok = not hit
Expand Down Expand Up @@ -730,6 +775,9 @@ def parse_finding_metadata(text: str) -> dict:
"""Best-effort parse of YAML-ish frontmatter + section content."""
md = {"title": "", "severity": "Medium", "asset": "", "endpoint": "",
"summary": "", "steps": "", "impact": "", "remediation": ""}
# A UTF-8 BOM would push `---` off the start, and Windows CRLF line endings
# (same platform) break the `^---\n` anchor — normalize both (#200).
text = text.lstrip("").replace("\r\n", "\n")
# YAML frontmatter
m = re.match(r"^---\n(.*?)\n---\n(.*)", text, re.S)
body = text
Expand Down Expand Up @@ -964,6 +1012,14 @@ def cmd_surface(args: argparse.Namespace) -> int:
# Main dispatcher
# ============================================================
def main() -> int:
# Windows/non-UTF-8 consoles default stdout to the code page (cp1252), which
# crashes on the check/cross/arrow/em-dash glyphs the CLI prints. Force UTF-8
# (matches engine/engine.py:main).
for _stream in (sys.stdout, sys.stderr):
try:
_stream.reconfigure(encoding="utf-8")
except (AttributeError, ValueError):
pass
parser = argparse.ArgumentParser(
prog="cbh",
description=("claude-bughunter CLI — terminal-native deterministic runner.\n"
Expand Down
7 changes: 7 additions & 0 deletions scripts/setup_harness_mcp.py
Original file line number Diff line number Diff line change
Expand Up @@ -227,6 +227,13 @@ def _wire(name, cmd, args, env, a):


def main():
# Windows/non-UTF-8 consoles default stdout to cp1252, which crashes on the
# check/cross/arrow glyphs this script prints. Force UTF-8 (see #180).
for _stream in (sys.stdout, sys.stderr):
try:
_stream.reconfigure(encoding="utf-8")
except (AttributeError, ValueError):
pass
ap = argparse.ArgumentParser()
ap.add_argument("--burp", action="store_true", help="wire the Burp MCP (default if no server flag given)")
ap.add_argument("--hackerone", action="store_true", help="wire the in-repo HackerOne MCP")
Expand Down
56 changes: 40 additions & 16 deletions skills/offensive-osint/scripts/h1_reference.py
Original file line number Diff line number Diff line change
Expand Up @@ -127,35 +127,57 @@ def gql_vars(query: str, variables: dict) -> dict:
sys.exit(1)


def lookup_program(handle: str) -> Optional[str]:
def lookup_program(handle: str) -> Optional[dict]:
"""Resolve a program handle to its team record, or None if not found/private.
Returns the team dict so the caller can use the canonical `handle` H1 stores
(TeamLookup is case-insensitive, but the hacktivity query_string is not, so
`--program Shopify` must query the canonical `shopify`, not the raw input)."""
data = gql_vars(TEAM_LOOKUP_QUERY, {"handle": handle})
team = data.get("data", {}).get("team")
team = (data.get("data") or {}).get("team")
if not team:
print(f"[!] Program '{handle}' not found or is private", file=sys.stderr)
return None
print(f"[+] {team['handle']} → id={team['_id']}, name={team['name']}")
return team["_id"]
# Progress goes to stderr so --json stdout stays clean and pipeable (jq).
print(f"[+] {team['handle']} → id={team['_id']}, name={team['name']}", file=sys.stderr)
return team


def build_page_query(args, after: Optional[str] = None) -> str:
"""
Build an inline GraphQL query for one page of results.
H1 crash rules (discovered empirically):
H1 crash/schema rules (discovered empirically):
- substate filter + sort + report fields → CRASH
- disclosed_at field + substate filter → CRASH
- named variables + substate filter + report fields → CRASH
- terms: {team_id: ...} is no longer searchable on CompleteHacktivityReportIndex
Strategy:
- Program filter (--program): query_string "team_handle:<handle>" (supports sort + pagination)
- Pure sort (no --program): no substate filter, sort works fine
- Program filter: substate filter, no sort, client-side sort
- Default: substate filter, no sort
"""
has_sort = args.top_voted or args.top_bounty
has_program = bool(args.program_id)

after_str = f', after: "{_escape(after)}"' if after else ""

if has_sort and not has_program:
if has_program:
# H1 dropped team_id filtering; query_string with team_handle works and
# still accepts sort + pagination.
sort_str = ""
if has_sort:
sort_field = "votes" if args.top_voted else "total_awarded_amount"
sort_str = f', sort: {{field: "{sort_field}", direction: DESC}}'
qs = _escape(f"team_handle:{args.program}")
return (
f'{{ search(index: CompleteHacktivityReportIndex, '
f'query_string: "{qs}", '
f'first: {PAGE_SIZE}{after_str}{sort_str}) '
f'{{ total_count pageInfo {{ endCursor }} nodes {{ {REPORT_FIELDS} }} }} }}'
)
elif has_sort:
# Sort-only mode: no substate filter, works without crashing
sort_field = "votes" if args.top_voted else "total_awarded_amount"
return (
Expand All @@ -164,14 +186,10 @@ def build_page_query(args, after: Optional[str] = None) -> str:
f'{{ total_count pageInfo {{ endCursor }} nodes {{ {REPORT_FIELDS} }} }} }}'
)
else:
# Filter mode: substate + optional team filter, no sort
filter_parts = ['terms: {substate: ["resolved"]}']
if has_program:
filter_parts.append(f'terms: {{team_id: ["{_escape(str(args.program_id))}"]}}')
filter_str = ", ".join(f"{{{p}}}" for p in filter_parts)
# Default filter mode: substate only, no sort
return (
f'{{ search(index: CompleteHacktivityReportIndex, '
f'query: {{bool: {{filter: [{filter_str}]}}}}, '
f'query: {{bool: {{filter: [{{terms: {{substate: ["resolved"]}}}}]}}}}, '
f'first: {PAGE_SIZE}{after_str}) '
f'{{ total_count pageInfo {{ endCursor }} nodes {{ {REPORT_FIELDS} }} }} }}'
)
Expand Down Expand Up @@ -359,10 +377,16 @@ def main():
return

args.program_id = None
if args.program:
args.program_id = lookup_program(args.program)
if not args.program_id:
if args.program is not None:
handle = args.program.strip()
if not handle:
print("[!] --program requires a non-empty handle", file=sys.stderr)
sys.exit(1)
team = lookup_program(handle)
if not team:
sys.exit(1)
args.program = team["handle"] # canonical handle for the query_string
args.program_id = team["_id"]

nodes = fetch_all_pages(args)
results = apply_client_filters(nodes, args)
Expand Down
34 changes: 34 additions & 0 deletions tests/test_cbh_windows_encoding.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,34 @@
"""Regression test for #180 (cbh UnicodeEncodeError on non-UTF-8 consoles).
The cbh CLI prints the glyphs the gate uses — the check/cross marks and the
arrow — throughout its output. On a Windows console the default code page is
cp1252, which cannot encode them, so a bare print() raised UnicodeEncodeError
and the command died mid-run. We reproduce that deterministically on any host by
forcing an ASCII default encoding (PYTHONUTF8=0 + PYTHONCOERCECLOCALE=0 +
LC_ALL=C), which is what Windows hits with cp1252.
"""
import os
import subprocess
import sys
import tempfile
import unittest
from pathlib import Path

_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
_ASCII_ENV = dict(os.environ, PYTHONUTF8="0", PYTHONCOERCECLOCALE="0", LC_ALL="C")


class CbhWindowsEncodingTests(unittest.TestCase):
def test_triage_survives_ascii_locale(self):
with tempfile.TemporaryDirectory() as tmp:
finding = Path(tmp) / "finding.md"
finding.write_text("# clickjacking on logout page\n", encoding="utf-8")
r = subprocess.run(
[sys.executable, "cbh/cli.py", "triage", str(finding)],
cwd=_REPO, env=_ASCII_ENV, capture_output=True, text=True, encoding="utf-8")
self.assertNotIn("UnicodeEncodeError", r.stderr,
f"cbh crashed under ASCII locale:\n{r.stderr}")


if __name__ == "__main__":
unittest.main()
63 changes: 63 additions & 0 deletions tests/test_h1_reference.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,63 @@
"""build_page_query must filter programs with query_string:team_handle, not the
team_id terms filter the H1 schema no longer accepts (#206, #202).
No network: build_page_query is a pure string builder over an args namespace.
"""
import argparse
import importlib.util
import os
import unittest
from unittest.mock import patch

_REPO = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
_H1 = os.path.join(_REPO, "skills", "offensive-osint", "scripts", "h1_reference.py")
_spec = importlib.util.spec_from_file_location("h1_reference", _H1)
h1 = importlib.util.module_from_spec(_spec)
_spec.loader.exec_module(h1)


def _args(program=None, program_id=None, top_voted=False, top_bounty=False):
return argparse.Namespace(program=program, program_id=program_id,
top_voted=top_voted, top_bounty=top_bounty)


class BuildPageQueryTests(unittest.TestCase):
def test_program_uses_team_handle_not_team_id(self):
q = h1.build_page_query(_args(program="acme", program_id="123"))
self.assertIn("query_string:", q)
self.assertIn("team_handle:acme", q)
self.assertNotIn("team_id", q)

def test_program_with_sort_adds_server_side_sort(self):
q = h1.build_page_query(_args(program="acme", program_id="123", top_voted=True))
self.assertIn("team_handle:acme", q)
self.assertIn('field: "votes"', q)

def test_sort_only_has_no_substate_filter(self):
q = h1.build_page_query(_args(top_bounty=True))
self.assertIn('field: "total_awarded_amount"', q)
self.assertNotIn("substate", q)

def test_default_mode_filters_resolved_without_team_id(self):
q = h1.build_page_query(_args())
self.assertIn('substate: ["resolved"]', q)
self.assertNotIn("team_id", q)


class LookupProgramTests(unittest.TestCase):
def test_returns_team_with_canonical_handle(self):
# TeamLookup is case-insensitive; the caller needs the canonical handle
# because the hacktivity query_string is not.
resp = {"data": {"team": {"_id": "42", "handle": "shopify", "name": "Shopify"}}}
with patch.object(h1, "gql_vars", return_value=resp):
team = h1.lookup_program("Shopify")
self.assertEqual(team["handle"], "shopify")
self.assertEqual(team["_id"], "42")

def test_returns_none_when_private_or_missing(self):
with patch.object(h1, "gql_vars", return_value={"data": {"team": None}}):
self.assertIsNone(h1.lookup_program("nope"))


if __name__ == "__main__":
unittest.main()
36 changes: 36 additions & 0 deletions tests/test_report_utf8_bom.py
Original file line number Diff line number Diff line change
@@ -0,0 +1,36 @@
"""A UTF-8 BOM before the YAML frontmatter must not break metadata parsing.
Editors on Windows (and some export tools) prepend a BOM (\\ufeff). The
frontmatter regex anchors on `^---`, which the BOM pushes off the start of the
string, so severity/asset silently fell back to defaults. Reported in #200.
"""
import unittest

from cbh import cli


class ReportUtf8BomTests(unittest.TestCase):
def test_bom_prefixed_frontmatter_still_parses(self):
finding = (
"---\nseverity: Low\nasset: example.test\n---\n"
"# Sample report\n\n## Summary\nA formatting example.\n"
)
for prefix in ("", ""):
with self.subTest(bom=bool(prefix)):
md = cli.parse_finding_metadata(prefix + finding)
self.assertEqual(md["severity"], "Low")
self.assertEqual(md["asset"], "example.test")
self.assertEqual(md["title"], "Sample report")

def test_crlf_frontmatter_still_parses(self):
"""Windows line endings (CRLF) — the same platform as the BOM — must parse too."""
finding = (
"---\nseverity: High\nasset: crlf.test\n---\n# CRLF report\n"
).replace("\n", "\r\n")
md = cli.parse_finding_metadata(finding)
self.assertEqual(md["severity"], "High")
self.assertEqual(md["asset"], "crlf.test")


if __name__ == "__main__":
unittest.main()
Loading
Loading