dscan-security 0.1.0__py3-none-any.whl

dscan/__init__.py

@@ -0,0 +1,20 @@
+"""dscan — an open source agent security suite.
+
+Wrap your agent with :func:`watch` to trace, redact, and scan its
+behavior, then inspect everything in a local dashboard::
+
+    from dscan import watch
+
+    @watch
+    async def my_agent(task: str):
+        ...  # your agent code unchanged
+
+    # then, from the shell:
+    # dscan dashboard  # localhost:4321
+"""
+
+from dscan.watcher import watch
+
+__version__ = "0.1.0"
+
+__all__ = ["watch", "__version__"]

dscan/cli.py

@@ -0,0 +1,263 @@
+"""dscan command-line interface.
+
+Defines the ``dscan`` Click command group and its subcommands: ``scan``
+(static prompt/MCP analysis via :mod:`dscan.scanner`), ``trail``
+(call-chain detection via :mod:`dscan.trail`), ``dashboard`` (launches
+:mod:`dscan.dashboard.server`), and ``watch`` (a usage reminder). All
+output is rendered with ``rich``. The package entry point ``dscan``
+resolves to :func:`main`.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+from dscan import __version__
+from dscan.trail import TrailAnalyzer
+
+console = Console()
+
+_SEVERITY_ORDER = ["high", "medium", "low"]
+_SEVERITY_STYLE = {"high": "bold red", "medium": "#f59e0b", "low": "cyan"}
+
+# Trail severities, lowest to highest, plus per-row table styles.
+_TRAIL_RANK = {"low": 0, "medium": 1, "high": 2, "critical": 3}
+_TRAIL_DISPLAY_ORDER = ["critical", "high", "medium", "low"]
+_TRAIL_ROW_STYLE = {"critical": "red", "high": "#f59e0b", "medium": "yellow", "low": None}
+
+
+def _ok(message: str) -> None:
+    console.print(f"[green]✓[/green] {message}")
+
+
+def _warn(message: str) -> None:
+    console.print(f"[#f59e0b]⚠[/#f59e0b] {message}")
+
+
+def _err(message: str) -> None:
+    console.print(f"[red]✗[/red] {message}")
+
+
+@click.group()
+@click.version_option(__version__, prog_name="dscan")
+def main() -> None:
+    """dscan — an open source agent security suite.
+
+    Trace and redact your agent's tool calls (@watch), statically scan
+    prompts and MCP configs (dscan scan), and inspect everything in a
+    local dashboard (dscan dashboard).
+    """
+
+
+@main.command()
+def watch() -> None:
+    """Show how to instrument an agent (it's a decorator, not a command)."""
+    _warn("Add @watch to your agent function. See README for usage.")
+
+
+@main.command()
+@click.argument("path", required=False, default=".")
+@click.option(
+    "--prompt",
+    "prompt_file",
+    type=click.Path(exists=True, dir_okay=False),
+    default=None,
+    help="Scan a single system-prompt file instead of a directory.",
+)
+def scan(path: str, prompt_file: str | None) -> None:
+    """Statically analyze agent configs and system prompts."""
+    from dscan.scanner import scan_directory, scan_file
+
+    findings = scan_file(prompt_file) if prompt_file else scan_directory(path)
+    _render_findings(findings)
+    if any(f.severity == "high" for f in findings):
+        sys.exit(1)
+
+
+@main.command()
+@click.option("--host", default="127.0.0.1", show_default=True, help="Host to bind.")
+@click.option("--port", default=4321, show_default=True, help="Port to bind.")
+@click.option(
+    "--open/--no-open",
+    "open_browser",
+    default=True,
+    show_default=True,
+    help="Open the dashboard in a browser.",
+)
+def dashboard(host: str, port: int, open_browser: bool) -> None:
+    """Launch the local trace dashboard."""
+    with console.status(
+        f"Starting dashboard at localhost:{port}...", spinner="dots"
+    ):
+        from dscan.dashboard.server import serve
+
+    _ok(f"Dashboard at [cyan]http://{host}:{port}[/cyan]  [dim](Ctrl-C to stop)[/dim]")
+    serve(host=host, port=port, open_browser=open_browser)
+
+
+@main.command()
+@click.argument("path")
+@click.option(
+    "--min-severity",
+    type=click.Choice(["low", "medium", "high", "critical"]),
+    default="low",
+    show_default=True,
+    help="Hide findings below this severity (display only; exit code still "
+    "reflects any high/critical finding).",
+)
+@click.option(
+    "--json",
+    "as_json",
+    is_flag=True,
+    default=False,
+    help="Output raw JSON instead of a rich table.",
+)
+def trail(path: str, min_severity: str, as_json: bool) -> None:
+    """Detect suspicious tool-call chains (CWAT) in trace files.
+
+    PATH is a trace file (.ndjson) or a directory of trace files.
+    """
+    target = Path(path)
+    if not target.exists():
+        _err(f"path not found: {path}")
+        sys.exit(2)
+
+    try:
+        traces = _load_trace_dicts(target)
+    except OSError as exc:  # pragma: no cover - defensive
+        _err(f"could not read traces from {path}: {exc}")
+        sys.exit(2)
+
+    # Analyze each session independently so chains never bridge unrelated
+    # agent runs (a read in one session + a send in another is not exfil).
+    analyzer = TrailAnalyzer()
+    all_findings: list = []
+    for session in _group_by_session(traces):
+        all_findings.extend(analyzer.analyze(session))
+
+    threshold = _TRAIL_RANK[min_severity]
+    shown = [f for f in all_findings if _TRAIL_RANK.get(f.severity, 0) >= threshold]
+    total_calls = len(traces)
+
+    if as_json:
+        console.print_json(data=[f.to_dict() for f in shown])
+    elif not all_findings:
+        _ok(f"No issues found in {total_calls} tool calls")
+    elif not shown:
+        console.print(
+            f"[dim]No findings at or above {min_severity.upper()} — "
+            f"{len(all_findings)} lower-severity finding(s) hidden.[/dim]"
+        )
+    else:
+        _render_trail(shown, total_calls)
+
+    if any(f.severity in ("high", "critical") for f in all_findings):
+        sys.exit(1)
+
+
+def _read_ndjson(path: Path) -> list[dict]:
+    traces: list[dict] = []
+    for line in path.read_text(encoding="utf-8", errors="replace").splitlines():
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            obj = json.loads(line)
+        except (json.JSONDecodeError, ValueError):
+            continue  # skip malformed lines
+        if isinstance(obj, dict):
+            traces.append(obj)
+    return traces
+
+
+def _load_trace_dicts(target: Path) -> list[dict]:
+    files = [target] if target.is_file() else sorted(target.glob("*.ndjson"))
+    traces: list[dict] = []
+    for file in files:
+        traces.extend(_read_ndjson(file))
+    return traces
+
+
+def _group_by_session(traces: list[dict]) -> list[list[dict]]:
+    groups: dict[str, list[dict]] = {}
+    order: list[str] = []
+    for trace in traces:
+        sid = str(trace.get("session_id") or "")
+        if sid not in groups:
+            groups[sid] = []
+            order.append(sid)
+        groups[sid].append(trace)
+    return [
+        sorted(groups[sid], key=lambda t: str(t.get("ts") or "")) for sid in order
+    ]
+
+
+def _render_trail(findings: list, total_calls: int) -> None:
+    table = Table(header_style="bold")
+    table.add_column("Severity")
+    table.add_column("Pattern")
+    table.add_column("Tools Involved")
+    table.add_column("Message")
+    table.add_column("Confidence", justify="right")
+    for severity in _TRAIL_DISPLAY_ORDER:
+        for f in (x for x in findings if x.severity == severity):
+            table.add_row(
+                severity.upper(),
+                f.pattern,
+                " → ".join(f.calls_involved),
+                f.message,
+                f"{round(f.confidence * 100)}%",
+                style=_TRAIL_ROW_STYLE.get(severity),
+            )
+    console.print(table)
+    console.print(
+        f"[bold]{len(findings)}[/bold] findings across "
+        f"[bold]{total_calls}[/bold] tool calls analysed"
+    )
+
+
+def _render_findings(findings: list) -> None:
+    if not findings:
+        _ok("No findings.")
+        return
+
+    for severity in _SEVERITY_ORDER:
+        group = [f for f in findings if f.severity == severity]
+        if not group:
+            continue
+        table = Table(
+            title=f"{severity.upper()} ({len(group)})",
+            title_style=_SEVERITY_STYLE[severity],
+            header_style="bold",
+            title_justify="left",
+        )
+        table.add_column("Rule")
+        table.add_column("File")
+        table.add_column("Line", justify="right")
+        table.add_column("Message")
+        table.add_column("Snippet")
+        for f in sorted(group, key=lambda x: (x.file, x.line, x.rule)):
+            table.add_row(
+                f.rule,
+                Path(f.file).name,
+                str(f.line),
+                f.message,
+                f.snippet,
+            )
+        console.print(table)
+
+    high = sum(1 for f in findings if f.severity == "high")
+    if high:
+        _err(f"{high} high-severity finding(s).")
+    else:
+        _warn(f"{len(findings)} finding(s), none high severity.")
+
+
+if __name__ == "__main__":
+    main()

dscan/dashboard/__init__.py

@@ -0,0 +1,10 @@
+"""dscan dashboard — local web UI for inspecting agent traces.
+
+This package holds the dashboard's aiohttp server (:mod:`dscan.dashboard.server`)
+and its single HTML template. The server reads NDJSON traces from
+``~/.dscan/traces`` (or ``DSCAN_TRACES_DIR``) and exposes them at
+``localhost:4321`` over a small JSON API plus a self-contained page that
+renders sessions, redacted tool calls, and trail findings. It depends
+only on ``aiohttp`` and ``aiofiles``; there are no external front-end
+dependencies.
+"""

dscan/dashboard/server.py

@@ -0,0 +1,184 @@
+"""Dashboard web server.
+
+A small aiohttp app that reads NDJSON traces and serves a local UI plus
+a JSON API:
+
+- ``GET /`` — the dashboard HTML with trace data injected.
+- ``GET /api/traces`` — all traces (newest first).
+- ``GET /api/traces/{session_id}`` — one session's detail.
+
+Traces are read from ``DSCAN_TRACES_DIR`` (default ``~/.dscan/traces``).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+import aiofiles
+from aiohttp import web
+
+__all__ = [
+    "read_traces",
+    "build_sessions",
+    "compute_stats",
+    "make_app",
+    "serve",
+]
+
+_TEMPLATE = Path(__file__).parent / "templates" / "index.html"
+
+# Typed application key for the configured traces directory.
+_TRACES_DIR_KEY: web.AppKey[Any] = web.AppKey("traces_dir", object)
+
+
+def _resolve_dir(traces_dir: str | os.PathLike[str] | None) -> Path:
+    if traces_dir is not None:
+        return Path(traces_dir)
+    env = os.environ.get("DSCAN_TRACES_DIR")
+    if env:
+        return Path(env)
+    return Path.home() / ".dscan" / "traces"
+
+
+def _utc_today() -> str:
+    return datetime.now(timezone.utc).strftime("%Y-%m-%d")
+
+
+async def read_traces(traces_dir: str | os.PathLike[str] | None = None) -> list[dict[str, Any]]:
+    """Read and parse every NDJSON trace, newest (by ``ts``) first.
+
+    Malformed lines are skipped rather than raising.
+    """
+    directory = _resolve_dir(traces_dir)
+    if not directory.is_dir():
+        return []
+
+    traces: list[dict[str, Any]] = []
+    for path in sorted(directory.glob("*.ndjson")):
+        async with aiofiles.open(path, encoding="utf-8") as f:
+            content = await f.read()
+        for line in content.splitlines():
+            line = line.strip()
+            if not line:
+                continue
+            try:
+                obj = json.loads(line)
+            except (json.JSONDecodeError, ValueError):
+                continue
+            if isinstance(obj, dict):
+                traces.append(obj)
+
+    traces.sort(key=lambda t: str(t.get("ts") or ""), reverse=True)
+    return traces
+
+
+def build_sessions(traces: list[dict[str, Any]]) -> list[dict[str, Any]]:
+    """Group traces into sessions, newest session first."""
+    sessions: dict[str, dict[str, Any]] = {}
+    for trace in traces:
+        sid = str(trace.get("session_id") or "unknown")
+        session = sessions.get(sid)
+        if session is None:
+            session = {
+                "session_id": sid,
+                "agent": trace.get("agent", "agent"),
+                "ts": trace.get("ts", ""),
+                "flagged": False,
+                "calls": [],
+            }
+            sessions[sid] = session
+        session["calls"].append(trace)
+        if trace.get("flagged"):
+            session["flagged"] = True
+        if str(trace.get("ts") or "") > str(session["ts"] or ""):
+            session["ts"] = trace.get("ts", "")
+
+    result = list(sessions.values())
+    for session in result:
+        session["calls"].sort(key=lambda c: str(c.get("ts") or ""))
+        session["count"] = len(session["calls"])
+    result.sort(key=lambda s: str(s.get("ts") or ""), reverse=True)
+    return result
+
+
+def compute_stats(traces: list[dict[str, Any]]) -> dict[str, int]:
+    """Top-bar stats: calls today, total flagged, agents active, and the
+    count of CRITICAL trail findings today (distinct from secrets flags)."""
+    today = _utc_today()
+    todays = [t for t in traces if str(t.get("ts") or "").startswith(today)]
+    return {
+        "total_calls_today": len(todays),
+        "flagged": sum(1 for t in traces if t.get("flagged")),
+        "agents_active": len({t.get("agent") for t in todays}),
+        "critical": sum(
+            1
+            for t in todays
+            for f in (t.get("trail_findings") or [])
+            if isinstance(f, dict) and f.get("severity") == "critical"
+        ),
+    }
+
+
+# --------------------------------------------------------------------------
+# HTTP handlers
+# --------------------------------------------------------------------------
+async def _index(request: web.Request) -> web.Response:
+    traces = await read_traces(request.app[_TRACES_DIR_KEY])
+    async with aiofiles.open(_TEMPLATE, encoding="utf-8") as f:
+        template = await f.read()
+    data = json.dumps(traces).replace("<", "\\u003c")
+    html = template.replace("__DSCAN_DATA__", data)
+    return web.Response(text=html, content_type="text/html")
+
+
+async def _traces(request: web.Request) -> web.Response:
+    return web.json_response(await read_traces(request.app[_TRACES_DIR_KEY]))
+
+
+async def _session(request: web.Request) -> web.Response:
+    sid = request.match_info["session_id"]
+    sessions = build_sessions(await read_traces(request.app[_TRACES_DIR_KEY]))
+    for session in sessions:
+        if session["session_id"] == sid:
+            return web.json_response(session)
+    return web.json_response({"error": "session not found"}, status=404)
+
+
+def make_app(traces_dir: str | os.PathLike[str] | None = None) -> web.Application:
+    """Build the dashboard aiohttp application."""
+    app = web.Application()
+    app[_TRACES_DIR_KEY] = traces_dir
+    app.add_routes(
+        [
+            web.get("/", _index),
+            web.get("/api/traces", _traces),
+            web.get("/api/traces/{session_id}", _session),
+        ]
+    )
+    return app
+
+
+def serve(
+    host: str = "127.0.0.1",
+    port: int = 4321,
+    *,
+    open_browser: bool = True,
+    traces_dir: str | os.PathLike[str] | None = None,
+) -> None:
+    """Run the dashboard server (blocking)."""
+    app = make_app(traces_dir)
+
+    if open_browser:
+
+        async def _open(_: web.Application) -> None:
+            import webbrowser
+
+            webbrowser.open(f"http://{host}:{port}")
+
+        app.on_startup.append(_open)
+
+    web.run_app(app, host=host, port=port, print=None)