探驪 Tanli

"The pearl worth a thousand taels of gold lies beneath the chin of the dragon, in the deepest of nine abysses." — Zhuangzi

English | 繁體中文

License: Apache-2.0 · Security & Responsible Use · Contributing

An autonomous red-team agent that assesses both LLM applications and classic web services. Dive into the abyss of the target; come back with the pearl of the finding.

Tanli is an autonomous red-team testing agent: you give it an authorized target, and it plans multi-step attack paths on its own, invokes tools, runs probes, judges results, and produces a structured security report with reproduction steps.

Authorized testing only. Scanning or attacking any system without authorization is illegal in most jurisdictions. By using this tool you agree to test only targets for which you hold explicit written authorization. See SECURITY.md.

Why "Tanli" (探驪)

The name comes from the idiom 探驪得珠 ("diving for the dragon's pearl"; also written 探珠驪頷), from the Zhuangzi, chapter Lie Yukou: the pearl is said to hide beneath the chin of the 驪龍, a dark dragon that dwells in the deepest abyss — to win it, one must dive to the bottom of the abyss, wait for the dragon to fall asleep, and seize it only then. It originally meant winning a treasure of immense value, and later also described writing that grasps the very essence of a subject.

Red teaming is that same dive: the truly critical vulnerabilities hide in the depths of the system, with defenses coiled beside them like the sleeping dragon — you plan stealthily, take your moment, and retrieve the pearl.

• The abyss = the target system (a black box of unknown depth)
• The sleeping dragon = the defenses you must not wake (low-noise, stealthy tradecraft)
• The strike = multi-step autonomous planning: probe → hypothesize → exploit → judge → review
• The pearl = the real vulnerability (with a CVSS score and a PoC)

Dual attack surface

Execution map

One CLI, three execution paths — all traffic to the target passes through the same safety fence; only run/scan can reach the Docker scanners, and the autonomous agent tool-loop never touches port scans or sqlmap. CVE lookups are pure control-plane traffic (GHSA/OSV/NVD, zero target probes).

Core capabilities

• Multi-step autonomous execution: DAG planner + ReAct execution loop; the attack surface is routed automatically by target type
• Scanner automation: nuclei / sqlmap / OWASP ZAP run fully autonomously inside Docker sandboxes; results are converted into findings automatically
• LLM attack playbooks: eleven OWASP GenAI playbooks covering direct jailbreak, multi-turn escalation (Crescendo/Many-shot/Skeleton Key), persona virtualization, encoding obfuscation (Base64/cipher/low-resource/ASCII-art), indirect-injection weaponization (zero-click exfil/confused deputy/memory poisoning), reasoning-model attacks (Bad Likert Judge/Echo Chamber) and multimodal injection — baseline control + sentinel markers + deterministic rules + an LLM-judge second pass for false-positive filtering
• Framework & infrastructure exposure playbooks: thirty-six web methodology playbooks — SQLi/XSS/SSRF/SSTI/CSRF/BOLA full-spectrum plus the CMS/framework misconfiguration family: WordPress config backups & xmlrpc amplification, Laravel .env / Django DEBUG / phpinfo probes, Spring Boot Actuator /heapdump, exposed .git & SourceMaps, plus the internet-scanner family: unauthenticated Redis/Elasticsearch, Jenkins/Tomcat admin consoles, Docker/K8s control planes, subdomain takeover, JWT stack flaws — plus field-distilled differential-testing playbooks (same-controller gate differentials, date-window pulls with negative-result foolproofing, WAF coverage differential + JS string-syntax-break detection) — all passive, evidence-only (endpoint + status + hash; leaked secrets are never downloaded or quoted)
• Automatic CVSS v3.1 scoring: the official formula embedded (zero deviation from the authoritative library across all 2,592 vectors), with severity/category → vector mapping
• Human review gate: every High/Critical finding is flagged "awaiting human confirmation"; the CLI warns explicitly until the report is finalized, so drafts never get published as official reports
• Signed authorization model: localhost-only by default; widening scope requires an Ed25519 JWS-signed credential plus mandatory Scope Statement validation — crossing the line aborts the run
• Offline lab self-test: built-in TargetLab (a pure-stdlib dual-behavior vulnerable/hardened lab including an LLM chat endpoint); one self-test command validates the whole engine end-to-end — no Docker, no external network
• Reporting: Markdown reports with CVSS vectors, PoC reproduction steps, exfiltrated data / achieved impact, and remediation advice deduplicated by OWASP category

Installation

Requires Python >= 3.11.

# from PyPI (recommended — stable releases)
pip install tanli

# smoke test (no dependencies)
tanli --help

From source (latest main, or for development):

git clone https://github.com/ADT109119/Tanli.git && cd Tanli
pip install -e .

Full-auto scanner mode requires Docker (pulls the official nuclei/sqlmap/zap images); the LLM judge requires any OpenAI-compatible endpoint (optional — falls back to deterministic rules without it).

Quick start

# 1. Offline self-test: spins up the local lab, 8 assertions end-to-end (recommended first step)
tanli self-test

# 2. Preview the plan against a local target (no actual attacks)
tanli run http://127.0.0.1:8080 -t web_service --dry-run

# 3. Fully automated web scan (scanners + judge + CVSS + report)
tanli run http://127.0.0.1:8080 -t web_service --scanners all

# 4. LLM app red-team (target is an OpenAI-compatible chat/completions endpoint)
tanli run http://127.0.0.1:8080 -t llm_app --scanners llm_playbook

# 5. Single scanner / single playbook
tanli scan http://127.0.0.1:8080 --scanner nuclei
tanli run http://127.0.0.1:8080 -t llm_app --playbook src/redteam/playbooks/llm/playbook_1.yaml

# 6. CVE lookup: exact CVE id, or product-level (ALL published CVEs of a package/framework)
#    Enriched with EPSS exploit-likelihood + CISA KEV (known-exploited) flags.
tanli cve CVE-2025-55182
tanli cve django -e pip            # GHSA + OSV merged, no version filter
tanli cve nginx                    # non-package ecosystems fall back to NVD keyword search

# 7. Autonomous agent mode: LLM tool-loop plans every step itself
#    (fingerprint -> product-level CVE lookup -> dynamic attempt; never trusts
#     self-reported versions). All tools run inside ScopeGuard/read-only/budget fences.
#    Engagement discipline: --roe loads a Rules-of-Engagement file and injects
#    RoE + MITRE ATT&CK-mapped OPPLAN before the first packet (Decepticon-style);
#    --workspace gives per-target cross-session memory + large-output offload
#    (RedAmon-style); a scratchpad working-memory tool + finish gate keep long
#    runs on-task; --context-window guards against context blowouts (auto-compress);
#    target responses pass prompt-injection guards.
tanli agent http://127.0.0.1:8080 --steps 30 --probes 60
tanli agent TARGET --auth-cred credential.jws --public-key signer_public.pem --read-only
tanli agent TARGET --context-window 200000 --context-compress-at 24000   # long runs
tanli agent TARGET --report-dir ~/tanli-data/reports                     # reports elsewhere
tanli roe --init roe.yaml && tanli agent TARGET --roe roe.yaml

--scanners: auto (default: web → all, llm_app → playbooks) | none | web_config | nuclei | sqlmap | zap | llm_playbook. ZAP depth: --zap-mode baseline|full|api; nuclei narrowing: --nuclei-severity, --nuclei-exclude-protocols. Agent context control: --context-window 0 (default: no limit; when set, uses API-reported prompt_tokens and deep-compresses near the limit), --context-compress-at <chars> (compress threshold, default 24000), --token-budget 0 (unlimited; hard caps remain --steps/--probes). Brain sampling overrides via REDTEAM_AGENT_TEMPERATURE, REDTEAM_AGENT_MAX_TOKENS, REDTEAM_AGENT_EXTRA_BODY (JSON, pass-through for gateway thinking toggles).

Authorization model

The default scope is limited to localhost / 127.0.0.1 / example.com. Operating against any internal or external target requires a signed credential:

# Issue an authorization credential with an Ed25519 private key
tanli gen-cred --scope scope.yaml --key signer_private.pem --out credential.jws

# Run with the credential
tanli run TARGET --auth-cred credential.jws --public-key signer_public.pem

ScopeGuard checks every request against the credential scope; any violation aborts the run with an audit trail. This is a hard gate, not a warning.

LLM judge setup

Judging uses any OpenAI-compatible endpoint, provider-agnostic:

export REDTEAM_JUDGE_BASE_URL="https://your-endpoint/v1"   # vLLM / ollama / cloud — anything
export REDTEAM_JUDGE_MODEL="your-model"
export REDTEAM_JUDGE_API_KEY="***"          # optional for local endpoints

• Deterministic parameters (temperature=0, fixed seed) for reproducibility
• Graceful degradation without an endpoint: LLM judging is skipped, deterministic rules only — the scan flow is unaffected

LLM attack playbooks

Safety by design: all payloads are benignized (payload_policy: benign), token-budget circuit breaker, and any playbook with side effects requires an authorization credential.

Playbooks double as the autonomous agent's attack-theory knowledge base: tanli agent exposes a get_playbook tool (catalog / keyword / OWASP filters) so the LLM plans against standard procedures instead of improvising — no vector store needed, the YAMLs are the knowledge base, fully auditable. Web methodology playbooks (e.g. web-006 SQLi flow) are queryable reference; execution still goes through the scanner pipeline under ScopeGuard/read-only fences.

Reports

Every run outputs report_<target>_<timestamp>.md in the current working directory (override with --report-dir <dir>, created if missing):

1. Executive summary with severity statistics (including the count of unreviewed high-risk findings)
2. OWASP category rollup (including the OWASP GenAI LLM surface)
3. Per finding: CVSS v3.1 vector and score, PoC reproduction steps, evidence, human-review status
4. Remediation advice: category → OWASP class → generic three-tier mapping, automatically deduplicated

For AI agents

This repo ships an agent-facing skill file: SKILL.md — a compact operations manual (any AI agent: Hermes / OpenCode / Codex / Claude Code) covering the six-step engagement flow (RoE → credential → agent run → report review), command cheatsheet, safety fences, and battle-tested pitfalls (WAF false positives, CVE-source lag, token budgets, workspace memory). Read it before driving tanli autonomously.

Tanli's own agent also ingests user skills from ~/.tanli/skills/*.md at runtime (served through its get_playbook knowledge base — drop a file, no reinstall needed).

Development

pip install -e ".[dev]"
pytest tests/ -q          # 259 tests, fully offline
tanli self-test           # lab end-to-end smoke, all-PASS required

• Specification: SPECIFICATION-FINAL.md (v3.4, planned collaboratively by the agy + opencode dual-agent pipeline)
• Contributing: CONTRIBUTING.md · Security policy: SECURITY.md

Project status

M1–M6 complete: CLI / authorization model / planner / scanner bridge / findings conversion / LLM judge / fifty-five attack playbooks (11 LLM: 5 execution + 6 jailbreak-methodology; 44 web methodology incl. framework/CMS + infra exposure + field-distilled differential-testing families + business-logic/state-machine & request-origin-trust families distilled from public disclosure cases + an upstream triage-matrix layer for outsourced/legacy portals + embedded-component/forensic-triage/orphan-asset families) / CVSS scoring layer / report gate & remediation advice / dual-behavior lab self-test / RoE engagement discipline / workspace memory / EPSS-KEV CVE intelligence / triage scoring / user-injectable skills. v0.0.3 endurance layer: in-session context compression with --context-window guardrails, three-tier memory (scratchpad + regex search offload + finish gate), critical-finding watchdog, exfiltrated-data loop into report §3. v0.0.4: --report-dir output control, hardened CVE control-plane queries (per-host Accept headers, strict hostname token scoping, URL-encoding fixes, actionable 422 fallback guidance). v0.0.5: KB research distillation line — three new playbook families distilled from public disclosure cases (embedded editor/file-manager connector exposure web-043, read-only compromise-indicator triage with explicit ceasefire web-044, in-perimeter orphan assets & frontend third-party keys web-045) plus auth-bypass/disclosure triage reinforcements across web-006/023/032/037/042. v0.0.6: post-authentication authorization-gap inventory for freshly migrated business systems (web-046) and vertical-SaaS tenant-boundary family for franchise/POS backends (web-047), plus absence-based filing for destructive-write endpoints, credential-tier PII grading, identifier-structure inference guard, vendor-pipeline root-cause framing and a third-sector industry anchor row across web-006/020/030/032/036/037/042/045. v0.0.7: unsafe-deserialization external-signal inventory (serialized-payload shape fingerprinting, self-generated-invalid-marker error differential, gadget-inventory-by-supply-chain, payload construction strictly forbidden — web-048) and numeric-semantics validation family (negative-quantity refunds, zero-price orders, discount-stacking integrity, zero-side-effect filing with source-level corroboration — web-049), plus reverse-DoS filing guard, enumerable-surface arithmetic, derivable-password lifecycle remediation, cross-site same-vendor cohort filing discipline and knowledge-drift orphan-asset signals across web-020/026/032/042/045; side_effect_free promoted to a first-class rendered field so long summaries can no longer truncate the safety flag. All 259 tests green.

License

Apache-2.0