lyrie-agent 0.3.0__py3-none-any.whl

lyrie/__init__.py

@@ -0,0 +1,78 @@
+"""
+Lyrie Agent — Python SDK.
+
+Lyrie.ai by OTT Cybersecurity LLC — https://lyrie.ai — MIT License.
+
+Embed the Shield Doctrine, Attack-Surface Mapper, Stages A–F validator,
+multi-language scanners, threat-intel client, HTTP proxy, and EditEngine
+in any Python project.
+"""
+
+from __future__ import annotations
+
+__all__ = [
+    "__version__",
+    "SIGNATURE",
+    # Shield Doctrine
+    "Shield",
+    "ShieldVerdict",
+    # Attack-Surface Mapper
+    "AttackSurfaceMapper",
+    "AttackSurface",
+    "EntryPoint",
+    "TrustBoundary",
+    "DataFlow",
+    "RiskHotspot",
+    # Stages A-F validator
+    "StagesValidator",
+    "ValidatedFinding",
+    "StageVerdict",
+    "Finding",
+    # Multi-language scanners
+    "scan_files",
+    "ScanReport",
+    # HTTP proxy
+    "HttpProxy",
+    "HttpExchange",
+    "Mutator",
+    # EditEngine
+    "EditEngine",
+    "EditPlan",
+    # Threat-Intel
+    "ThreatIntelClient",
+    "ThreatAdvisory",
+    # OSS-Scan
+    "run_oss_scan",
+    "OssScanResult",
+    # LyrieEvolve
+    "LyrieEvolve",
+    "TaskOutcome",
+    "SkillContext",
+    "TrainingEntry",
+    "ExtractionResult",
+]
+
+__version__ = "0.5.0"
+SIGNATURE: str = "Lyrie.ai by OTT Cybersecurity LLC"
+
+from lyrie.shield import Shield, ShieldVerdict
+from lyrie.attack_surface import (
+    AttackSurfaceMapper,
+    AttackSurface,
+    EntryPoint,
+    TrustBoundary,
+    DataFlow,
+    RiskHotspot,
+)
+from lyrie.stages import (
+    StagesValidator,
+    ValidatedFinding,
+    StageVerdict,
+    Finding,
+)
+from lyrie.scanners import scan_files, ScanReport
+from lyrie.proxy import HttpProxy, HttpExchange, Mutator
+from lyrie.edits import EditEngine, EditPlan
+from lyrie.threat_intel import ThreatIntelClient, ThreatAdvisory
+from lyrie.oss_scan import run_oss_scan, OssScanResult
+from lyrie.evolve import LyrieEvolve, TaskOutcome, SkillContext, TrainingEntry, ExtractionResult

lyrie/attack_surface.py

@@ -0,0 +1,438 @@
+"""
+Lyrie Attack-Surface Mapper — Python port.
+
+Lyrie.ai by OTT Cybersecurity LLC — https://lyrie.ai — MIT License.
+
+Builds a structural picture of what's worth attacking BEFORE any
+vulnerability scanner runs. Pure static analysis; never executes code,
+never opens a network socket. Every text it ingests passes the Shield.
+"""
+
+from __future__ import annotations
+
+import re
+import subprocess
+import time
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Final, Iterable, Literal, Optional, Pattern, Sequence
+
+from lyrie.shield import Shield, ShieldVerdict
+
+MAPPER_VERSION: Final[str] = "lyrie-asm-py-1.0.0"
+SIGNATURE: Final[str] = "Lyrie.ai by OTT Cybersecurity LLC"
+
+EntryKind = Literal[
+    "http-route", "cli-command", "file-reader", "env-consumer",
+    "deserialization-sink", "subprocess", "render", "websocket", "cron",
+]
+BoundaryKind = Literal[
+    "auth-gate", "rbac-check", "rate-limit", "sandbox-cross",
+    "shell-exec", "network-egress", "shield-gate",
+]
+FlowSource = Literal[
+    "http-input", "cli-arg", "env-var", "file-read", "network-fetch",
+    "user-message", "mcp-tool-result", "memory-recall",
+]
+FlowSink = Literal[
+    "shell", "filesystem-write", "sql", "http-output",
+    "agent-prompt", "tool-call", "deserialization",
+]
+
+
+@dataclass(slots=True)
+class EntryPoint:
+    kind: EntryKind
+    file: str
+    line: int
+    evidence: str
+    detail: dict[str, str] = field(default_factory=dict)
+
+
+@dataclass(slots=True)
+class TrustBoundary:
+    kind: BoundaryKind
+    file: str
+    line: int
+    evidence: str
+
+
+@dataclass(slots=True)
+class DataFlow:
+    source: FlowSource
+    sink: FlowSink
+    file: str
+    line: int
+    evidence: str
+    risk: int
+
+
+@dataclass(slots=True)
+class DependencyEntry:
+    name: str
+    version: Optional[str] = None
+    manifest: str = ""
+    ecosystem: str = "unknown"
+
+
+@dataclass(slots=True)
+class RiskHotspot:
+    file: str
+    score: int
+    reasons: list[str]
+
+
+@dataclass(slots=True)
+class AttackSurface:
+    root: str
+    files_inspected: int
+    files_ignored: int
+    files_shielded: int
+    entry_points: list[EntryPoint]
+    trust_boundaries: list[TrustBoundary]
+    data_flows: list[DataFlow]
+    dependencies: list[DependencyEntry]
+    hotspots: list[RiskHotspot]
+    generated_at: str
+    mapper_version: str = MAPPER_VERSION
+    signature: str = SIGNATURE
+
+
+# ─── Detector regexes ───────────────────────────────────────────────────────
+
+_ENTRY_DETECTORS: Final[Sequence[tuple[EntryKind, Pattern[str]]]] = (
+    ("http-route", re.compile(
+        r"\b(?:app|router|route|server|fastify|hono|elysia|express|koa)"
+        r"\.(get|post|put|patch|delete|all|use)\s*\(\s*[\"'`]([^\"'`]+)[\"'`]",
+        re.IGNORECASE,
+    )),
+    ("http-route", re.compile(r"@(?:Get|Post|Put|Patch|Delete|All)\s*\(\s*[\"'`]([^\"'`]+)[\"'`]")),
+    ("http-route", re.compile(r"@app\.route\(\s*[\"'`]([^\"'`]+)[\"'`]")),
+    ("http-route", re.compile(r"^\s*(?:async\s+)?def\s+\w+\s*\([^)]*request[^)]*\)", re.MULTILINE)),
+    ("cli-command", re.compile(r"\bprogram\.command\s*\(\s*[\"'`]([^\"'`]+)[\"'`]")),
+    ("cli-command", re.compile(r"\b@click\.command\(")),
+    ("cli-command", re.compile(r"\bcobra\.Command\s*\{")),
+    ("file-reader", re.compile(r"\b(readFileSync|readFile|fs\.readFile|os\.open|ioutil\.ReadFile)\b")),
+    ("file-reader", re.compile(r"\bopen\s*\([^)]*[\"'][^\"']+[\"']")),
+    ("env-consumer", re.compile(r"\bprocess\.env\.[A-Z_][A-Z0-9_]*")),
+    ("env-consumer", re.compile(r"\bos\.environ\b")),
+    ("env-consumer", re.compile(r"\bos\.getenv\s*\(\s*[\"'`]([A-Z_][A-Z0-9_]*)[\"'`]", re.IGNORECASE)),
+    ("deserialization-sink", re.compile(
+        r"\b(JSON\.parse|YAML\.parse|yaml\.load|pickle\.loads?|marshal\.loads?|deserialize|fromJSON)\b"
+    )),
+    ("subprocess", re.compile(
+        r"\b(exec|execSync|spawn|spawnSync|child_process|subprocess\.run|os\.system|exec\.Command)\b"
+    )),
+    ("render", re.compile(
+        r"\b(res\.render|renderTemplate|renderToString|render_template|template\.Execute)\b"
+    )),
+    ("websocket", re.compile(r"\b(new WebSocket|ws\.on\s*\(|wss\.on\s*\()")),
+    ("cron", re.compile(r"\b(cron\.schedule|new CronJob|@Cron|crontab)")),
+)
+
+_BOUNDARY_DETECTORS: Final[Sequence[tuple[BoundaryKind, Pattern[str]]]] = (
+    ("auth-gate", re.compile(
+        r"\b(authenticate|requireAuth|isAuthenticated|verifyToken|jwt\.verify|passport\.authenticate)\b"
+    )),
+    ("rbac-check", re.compile(r"\b(hasRole|requireRole|checkPermission|authorize|policy\.|rbac)\b", re.IGNORECASE)),
+    ("rate-limit", re.compile(r"\b(rateLimit|rate_limit|RateLimiter|throttle\(|express-rate-limit)\b", re.IGNORECASE)),
+    ("sandbox-cross", re.compile(r"\b(sandbox|vm\.createContext|nsjail|firejail|seccomp|chroot|namespaces)\b", re.IGNORECASE)),
+    ("shell-exec", re.compile(r"\b(execSync|spawnSync|os\.system|subprocess\.run)\b")),
+    ("network-egress", re.compile(r"\b(fetch\s*\(|http\.get|https\.get|requests\.get|net\.Dial)\b")),
+    ("shield-gate", re.compile(r"\b(scan_inbound|scan_recalled|ShieldGuard|ShieldManager|Shield\(\))\b")),
+)
+
+_FLOW_DETECTORS: Final[Sequence[tuple[FlowSource, FlowSink, Pattern[str], int]]] = (
+    ("user-message", "shell", re.compile(
+        r"\b(child_process\.(exec|spawn)|execSync|spawnSync|os\.system|subprocess\.(run|call|Popen))"
+        r"\s*\([^)]*\b(req|request|input|message|body|userInput|args\.[a-zA-Z_])\b",
+        re.IGNORECASE,
+    ), 9),
+    ("http-input", "sql", re.compile(
+        r"\b(query|execute|raw)\s*\(\s*[`'\"][^`'\"]*\$\{[^}]+\}",
+    ), 8),
+    ("env-var", "shell", re.compile(
+        r"(execSync|spawn|os\.system)\s*\([^)]*process\.env\.",
+    ), 7),
+    ("network-fetch", "agent-prompt", re.compile(
+        r"\b(fetch|http\.get|requests\.get)[^;]*\.(text|json)\(\)[^;]*\b(prompt|system|message)",
+        re.IGNORECASE,
+    ), 8),
+    ("file-read", "agent-prompt", re.compile(
+        r"\b(readFileSync|readFile)[^;]*\.\s*(prompt|system|content)",
+    ), 6),
+    ("memory-recall", "agent-prompt", re.compile(
+        r"\b(recall|searchAcrossSessions)\s*\(",
+    ), 4),
+)
+
+# ─── Ignore globs ────────────────────────────────────────────────────────────
+
+_IGNORE_PATTERNS: Final[Sequence[Pattern[str]]] = tuple(
+    re.compile(p)
+    for p in (
+        r"(^|/)\.next/",
+        r"(^|/)\.turbo/",
+        r"(^|/)node_modules/",
+        r"(^|/)dist/",
+        r"(^|/)build/",
+        r"(^|/)target/",
+        r"(^|/)\.git/",
+        r"(^|/)coverage/",
+        r"(^|/)__pycache__/",
+        r"\.lock$",
+        r"\.min\.(js|css)$",
+        r"\.map$",
+        r"\.png$",
+        r"\.jpg$",
+        r"\.jpeg$",
+        r"\.gif$",
+        r"\.webp$",
+        r"\.pdf$",
+        r"\.zip$",
+        r"\.tar\.gz$",
+    )
+)
+
+_TEXT_EXTS: Final[frozenset[str]] = frozenset({
+    ".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs",
+    ".py", ".pyi", ".go", ".rs", ".rb", ".java", ".kt", ".swift",
+    ".php", ".cs", ".cpp", ".cc", ".c", ".h", ".hpp",
+    ".sh", ".bash", ".zsh", ".fish",
+    ".html", ".vue", ".svelte",
+    ".yaml", ".yml", ".toml", ".json", ".env",
+})
+
+
+# ─── Public API ──────────────────────────────────────────────────────────────
+
+
+class AttackSurfaceMapper:
+    """
+    Lyrie Attack-Surface Mapper.
+
+    Lyrie.ai by OTT Cybersecurity LLC.
+    """
+
+    __slots__ = ("_root", "_files", "_max_files", "_max_bytes", "_shield", "_deps_only")
+
+    def __init__(
+        self,
+        root: str | Path = ".",
+        *,
+        files: Optional[Iterable[str]] = None,
+        max_files: int = 5_000,
+        max_bytes_per_file: int = 200_000,
+        shield: Optional[Shield] = None,
+        deps_only: bool = False,
+    ) -> None:
+        self._root = Path(root).resolve()
+        self._files = list(files) if files is not None else None
+        self._max_files = max_files
+        self._max_bytes = max_bytes_per_file
+        self._shield = shield or Shield()
+        self._deps_only = deps_only
+
+    def run(self) -> AttackSurface:
+        files = self._resolve_files()
+        entries: list[EntryPoint] = []
+        boundaries: list[TrustBoundary] = []
+        flows: list[DataFlow] = []
+        inspected = ignored = shielded = 0
+
+        if not self._deps_only:
+            for rel in files:
+                if any(p.search(rel) for p in _IGNORE_PATTERNS):
+                    ignored += 1
+                    continue
+                ext = Path(rel).suffix.lower()
+                if ext not in _TEXT_EXTS:
+                    ignored += 1
+                    continue
+                abs_path = self._root / rel
+                if not abs_path.is_file():
+                    continue
+                try:
+                    content = abs_path.read_text("utf-8", errors="replace")[: self._max_bytes]
+                except OSError:
+                    continue
+                if "lyrie-shield: ignore-file" in content[:4096]:
+                    ignored += 1
+                    continue
+
+                self._detect_into(content, rel, entries, boundaries, flows)
+                inspected += 1
+
+        deps = _collect_dependencies(self._root)
+        hotspots = _rank_hotspots(self._root, files, entries, boundaries, flows)
+
+        return AttackSurface(
+            root=str(self._root),
+            files_inspected=inspected,
+            files_ignored=ignored,
+            files_shielded=shielded,
+            entry_points=entries,
+            trust_boundaries=boundaries,
+            data_flows=flows,
+            dependencies=deps,
+            hotspots=hotspots,
+            generated_at=datetime.now(tz=timezone.utc).isoformat(),
+        )
+
+    # ── internals ──────────────────────────────────────────────────────────
+
+    def _resolve_files(self) -> list[str]:
+        if self._files is not None:
+            return self._files[: self._max_files]
+        return _list_repo_files(self._root, self._max_files)
+
+    def _detect_into(
+        self,
+        content: str,
+        file: str,
+        entries: list[EntryPoint],
+        boundaries: list[TrustBoundary],
+        flows: list[DataFlow],
+    ) -> None:
+        for kind, rx in _ENTRY_DETECTORS:
+            for m in rx.finditer(content):
+                entries.append(EntryPoint(
+                    kind=kind, file=file, line=_line_of(content, m.start()),
+                    evidence=_excerpt(content, m.start()),
+                ))
+        for kind, rx in _BOUNDARY_DETECTORS:
+            for m in rx.finditer(content):
+                boundaries.append(TrustBoundary(
+                    kind=kind, file=file, line=_line_of(content, m.start()),
+                    evidence=_excerpt(content, m.start()),
+                ))
+        for source, sink, rx, risk in _FLOW_DETECTORS:
+            for m in rx.finditer(content):
+                ev = _excerpt(content, m.start())
+                if self._shield.scan_recalled(ev).blocked:
+                    continue
+                flows.append(DataFlow(
+                    source=source, sink=sink, file=file,
+                    line=_line_of(content, m.start()),
+                    evidence=ev, risk=risk,
+                ))
+
+
+# ─── Helpers ────────────────────────────────────────────────────────────────
+
+
+def _line_of(content: str, idx: int) -> int:
+    return content.count("\n", 0, idx) + 1
+
+
+def _excerpt(content: str, idx: int, *, span: int = 80) -> str:
+    start = max(0, idx - 20)
+    end = min(len(content), idx + span)
+    return " ".join(content[start:end].split())
+
+
+def _list_repo_files(root: Path, limit: int) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", "-C", str(root), "ls-files"],
+            check=True, text=True, capture_output=True, timeout=15,
+        )
+        if result.stdout:
+            return [ln for ln in result.stdout.splitlines() if ln][:limit]
+    except (subprocess.CalledProcessError, subprocess.TimeoutExpired, FileNotFoundError):
+        pass
+    return _walk_dir(root, limit)
+
+
+def _walk_dir(root: Path, limit: int) -> list[str]:
+    out: list[str] = []
+    for path in root.rglob("*"):
+        if not path.is_file():
+            continue
+        rel = str(path.relative_to(root))
+        if any(p.search(rel) for p in _IGNORE_PATTERNS):
+            continue
+        out.append(rel)
+        if len(out) >= limit:
+            break
+    return out
+
+
+def _collect_dependencies(root: Path) -> list[DependencyEntry]:
+    deps: list[DependencyEntry] = []
+    pkg = root / "package.json"
+    if pkg.is_file():
+        try:
+            import json
+            data = json.loads(pkg.read_text("utf-8"))
+            for section in ("dependencies", "devDependencies", "peerDependencies"):
+                for name, version in (data.get(section) or {}).items():
+                    deps.append(DependencyEntry(
+                        name=name, version=str(version),
+                        manifest="package.json", ecosystem="npm",
+                    ))
+        except (OSError, ValueError):
+            pass
+    pyproject = root / "pyproject.toml"
+    if pyproject.is_file():
+        try:
+            content = pyproject.read_text("utf-8")
+            for m in re.finditer(r"^\s*([a-zA-Z0-9_\-]+)\s*=\s*[\"'][^\"']+[\"']", content, re.MULTILINE):
+                deps.append(DependencyEntry(
+                    name=m.group(1), manifest="pyproject.toml", ecosystem="pip",
+                ))
+        except OSError:
+            pass
+    return deps
+
+
+_KIND_WEIGHT: Final[dict[str, int]] = {
+    "http-route": 3, "websocket": 3,
+    "deserialization-sink": 4, "subprocess": 4,
+    "file-reader": 1, "env-consumer": 1,
+    "render": 2, "cli-command": 2, "cron": 2,
+}
+
+
+def _rank_hotspots(
+    root: Path,
+    files: list[str],
+    entries: list[EntryPoint],
+    boundaries: list[TrustBoundary],
+    flows: list[DataFlow],
+) -> list[RiskHotspot]:
+    scores: dict[str, dict] = {}
+
+    def bump(file: str, score: int, reason: str) -> None:
+        if file not in scores:
+            scores[file] = {"score": 0, "reasons": set()}
+        scores[file]["score"] += score
+        scores[file]["reasons"].add(reason)
+
+    for ep in entries:
+        bump(ep.file, _KIND_WEIGHT.get(ep.kind, 1), f"entry:{ep.kind}")
+    for tb in boundaries:
+        bump(tb.file, 1, f"boundary:{tb.kind}")
+    for f in flows:
+        bump(f.file, f.risk, f"flow:{f.source}->{f.sink}")
+
+    now = time.time()
+    for file in files:
+        path = root / file
+        try:
+            mtime = path.stat().st_mtime
+            if now - mtime < 30 * 24 * 3600 and file in scores:
+                scores[file]["score"] += 1
+                scores[file]["reasons"].add("recently-edited")
+        except OSError:
+            pass
+
+    return [
+        RiskHotspot(
+            file=file,
+            score=min(10, info["score"]),
+            reasons=sorted(info["reasons"]),
+        )
+        for file, info in sorted(scores.items(), key=lambda kv: -kv[1]["score"])[:25]
+    ]

lyrie/cli.py

@@ -0,0 +1,184 @@
+"""
+`lyrie-py` CLI — operator entry point for the Python SDK.
+
+Lyrie.ai by OTT Cybersecurity LLC — https://lyrie.ai — MIT License.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+from lyrie import (
+    AttackSurfaceMapper,
+    Finding,
+    Shield,
+    StagesValidator,
+    __version__,
+    scan_files,
+)
+from lyrie.threat_intel import ThreatIntelClient
+
+
+def _print_header(title: str) -> None:
+    print()
+    print(f"🛡️  {title}  ·  Lyrie.ai by OTT Cybersecurity LLC")
+    print("─" * 65)
+
+
+def _shield(args: argparse.Namespace) -> int:
+    shield = Shield()
+    text = " ".join(args.text)
+    verdict = shield.scan_recalled(text) if args.mode == "recalled" else shield.scan_inbound(text)
+    print(json.dumps({
+        "blocked": verdict.blocked,
+        "severity": verdict.severity,
+        "reason": verdict.reason,
+        "signature": verdict.signature,
+    }, indent=2))
+    return 0 if not verdict.blocked else 1
+
+
+def _understand(args: argparse.Namespace) -> int:
+    surface = AttackSurfaceMapper(root=args.root).run()
+    if args.json:
+        from dataclasses import asdict
+        print(json.dumps(asdict(surface), indent=2))
+        return 0
+    _print_header("Lyrie Attack-Surface Map")
+    print(f"  root:          {surface.root}")
+    print(f"  files seen:    {surface.files_inspected}  (ignored {surface.files_ignored})")
+    print(f"  entries:       {len(surface.entry_points)}")
+    print(f"  boundaries:    {len(surface.trust_boundaries)}")
+    print(f"  flows:         {len(surface.data_flows)}")
+    print(f"  dependencies:  {len(surface.dependencies)}")
+    if surface.hotspots:
+        print()
+        print("🔥 Top hotspots")
+        for h in surface.hotspots[:10]:
+            print(f"  [{h.score:>2}] {h.file}")
+            for r in h.reasons[:4]:
+                print(f"        {r}")
+    print()
+    print(f"signature: {surface.signature}")
+    print()
+    return 0
+
+
+def _scan_files(args: argparse.Namespace) -> int:
+    report = scan_files(root=args.root)
+    if args.json:
+        from dataclasses import asdict
+        print(json.dumps({
+            "scanned_files": report.scanned_files,
+            "findings": [asdict(f) for f in report.findings],
+            "languages": report.languages,
+            "signature": report.signature,
+        }, indent=2))
+        return 0
+    _print_header("Lyrie Multi-Language Scan")
+    print(f"  files scanned: {report.scanned_files}")
+    print(f"  findings:      {len(report.findings)}")
+    print(f"  languages:     {' '.join(f'{l}({n})' for l, n in report.languages)}")
+    print()
+    for f in report.findings[:50]:
+        print(f"  [{f.severity.upper():>8}] {f.title}")
+        print(f"             {f.file}:{f.line}")
+    print()
+    print(f"signature: {report.signature}")
+    print()
+    return 0
+
+
+def _validate(args: argparse.Namespace) -> int:
+    finding = Finding(
+        id=args.id,
+        title=args.title,
+        severity=args.severity,
+        description=args.description,
+        file=args.file,
+        line=args.line,
+        cwe=args.cwe,
+        category=args.category,  # type: ignore[arg-type]
+        evidence=args.evidence,
+    )
+    validator = StagesValidator()
+    v = validator.validate(finding)
+    print(json.dumps({
+        "confirmed": v.confirmed,
+        "confidence": round(v.confidence, 2),
+        "stages": [{"stage": s.stage, "passed": s.passed, "reason": s.reason}
+                    for s in v.stages],
+        "poc": v.poc.payload if v.poc else None,
+        "remediation": v.remediation.summary if v.remediation else None,
+        "signature": v.signature,
+    }, indent=2))
+    return 0
+
+
+def _intel(args: argparse.Namespace) -> int:
+    client = ThreatIntelClient(offline=args.offline)
+    ads = client.get_advisories()
+    if args.json:
+        from dataclasses import asdict
+        print(json.dumps([asdict(a) for a in ads], indent=2))
+        return 0
+    _print_header("Lyrie Threat-Intel")
+    if not ads:
+        print("  (no advisories — feed unreachable, offline, or empty)")
+    else:
+        for a in ads[:25]:
+            kev = " 🚨 KEV" if a.kev.in_kev else ""
+            print(f"  {a.cve}  [{a.severity.upper()}]{kev}  {a.title}")
+    print()
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="lyrie-py",
+        description=f"Lyrie Agent Python SDK CLI — Lyrie.ai by OTT Cybersecurity LLC (v{__version__})",
+    )
+    parser.add_argument("--version", action="version", version=f"lyrie-agent {__version__}")
+    sub = parser.add_subparsers(dest="cmd", required=True)
+
+    p_shield = sub.add_parser("shield", help="Run text through the Shield")
+    p_shield.add_argument("text", nargs="+")
+    p_shield.add_argument("--mode", choices=("recalled", "inbound"), default="recalled")
+    p_shield.set_defaults(func=_shield)
+
+    p_und = sub.add_parser("understand", help="Lyrie Attack-Surface Mapper")
+    p_und.add_argument("--root", default=".")
+    p_und.add_argument("--json", action="store_true")
+    p_und.set_defaults(func=_understand)
+
+    p_scan = sub.add_parser("scan-files", help="Lyrie multi-language scanners")
+    p_scan.add_argument("--root", default=".")
+    p_scan.add_argument("--json", action="store_true")
+    p_scan.set_defaults(func=_scan_files)
+
+    p_val = sub.add_parser("validate-finding", help="Run a finding through Stages A–F")
+    p_val.add_argument("--id", default="cli-1")
+    p_val.add_argument("--title", default="CLI test finding")
+    p_val.add_argument("--severity", default="high")
+    p_val.add_argument("--description", default="Submitted via lyrie-py CLI")
+    p_val.add_argument("--file")
+    p_val.add_argument("--line", type=int)
+    p_val.add_argument("--cwe")
+    p_val.add_argument("--category", default="other")
+    p_val.add_argument("--evidence", default="")
+    p_val.set_defaults(func=_validate)
+
+    p_intel = sub.add_parser("intel", help="Lyrie Threat-Intel feed")
+    p_intel.add_argument("--offline", action="store_true")
+    p_intel.add_argument("--json", action="store_true")
+    p_intel.set_defaults(func=_intel)
+
+    args = parser.parse_args(argv)
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    sys.exit(main())