dscan-security 0.1.0__tar.gz

dscan_security-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# Secrets and local config
+.env
+.env.*
+*.pem
+*.key
+dscan.yml          # local user config — never commit
+
+# dscan traces — never commit user data
+~/.dscan/
+.dscan/
+traces/
+
+# Python
+__pycache__/
+*.pyc
+*.py[cod]
+*$py.class
+.venv/
+venv/
+env/
+build/
+dist/
+.eggs/
+*.egg
+*.egg-info/
+
+# Tooling caches
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+.mypy_cache/
+.ruff_cache/
+.uv/
+
+# IDE
+.vscode/
+.idea/
+.cursor/
+
+# OS
+.DS_Store

dscan_security-0.1.0/PKG-INFO

@@ -0,0 +1,168 @@
+Metadata-Version: 2.4
+Name: dscan-security
+Version: 0.1.0
+Summary: Open source agent security suite — intercept, scan, and test your AI agents
+Project-URL: Homepage, https://deepscan.security
+Project-URL: Repository, https://github.com/DeepScan-Security/dscan
+Project-URL: Bug Tracker, https://github.com/DeepScan-Security/dscan/issues
+Project-URL: Changelog, https://github.com/DeepScan-Security/dscan/blob/main/CHANGELOG.md
+Author-email: DeepScan <security@deepscan.security>
+License: MIT
+Keywords: agent-security,ai-agents,devsecops,llm-security,mcp,prompt-injection,security
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Testing
+Requires-Python: >=3.11
+Requires-Dist: aiofiles>=23.0
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: anthropic>=0.25
+Requires-Dist: click>=8.0
+Requires-Dist: jinja2>=3.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# dscan
+
+[![CI](https://github.com/DeepScan-Security/dscan/actions/workflows/ci.yml/badge.svg)](https://github.com/DeepScan-Security/dscan/actions/workflows/ci.yml)
+![coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)
+[![PyPI](https://img.shields.io/pypi/v/dscan-security)](https://pypi.org/project/dscan-security/)
+[![Python](https://img.shields.io/pypi/pyversions/dscan-security)](https://pypi.org/project/dscan-security/)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+An open source agent security suite. Trace and redact your agent's tool
+calls, scan its prompts and MCP configs, and detect suspicious call
+chains — then inspect everything in a local dashboard.
+
+```bash
+pip install dscan-security
+```
+
+The package installs as `dscan-security`; the import path and CLI stay
+`dscan` (`import dscan`, `dscan --help`).
+
+![dscan dashboard](docs/dashboard.png)
+
+## Quick start
+
+```python
+from dscan import watch
+
+@watch
+async def my_agent(task: str):
+    ...  # your agent code, unchanged
+```
+
+Run your agent, then open the dashboard:
+
+```bash
+dscan dashboard
+```
+
+Tool calls are written as redacted NDJSON to `~/.dscan/traces/` (override
+with `DSCAN_TRACES_DIR`). Wrapping any tool with `@watch.tool` traces its
+params and result; if you use the Anthropic SDK, `@watch` also intercepts
+`messages.create()` and traces each `tool_use` block.
+
+## What dscan catches
+
+| Capability | What it detects |
+| --- | --- |
+| `@watch` (tracing) | Every tool call — name, params, result, duration — written as redacted NDJSON; flags calls whose params contain secrets |
+| Redaction | AWS keys, Anthropic/OpenAI/GitHub/Stripe tokens, JWTs, emails, phone numbers, SSNs, Luhn-valid credit cards, database-URL passwords, high-entropy secrets |
+| `dscan scan` | Permissive prompts, injection-prone prompts, hardcoded secrets, excessive tool scope; unverified, overprivileged, and credential-leaking MCP servers |
+| `dscan trail` | Suspicious tool-call sequences across an agent run (exfiltration, recon, injection relay, data staging, goal drift) |
+| `dscan dashboard` | Local web UI: sessions, per-call timeline, redacted values, secrets flags, and trail findings |
+
+## Commands
+
+### `dscan scan`
+
+Static analysis of system prompts and MCP config files in a directory.
+Exits `1` if any high-severity issue is found.
+
+```text
+$ dscan scan ./prompts
+                                  HIGH (1)
+┏━━━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Rule  ┃ File   ┃ Line ┃ Message                     ┃ Snippet           ┃
+┡━━━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ SP003 │ sp.txt │    2 │ Hardcoded secret in prompt  │ ...sk-ant-api03... │
+└───────┴────────┴──────┴─────────────────────────────┴───────────────────┘
+✗ 1 high-severity finding(s).
+```
+
+### `dscan watch`
+
+`@watch` is a decorator, not a runtime command. This prints a reminder:
+
+```text
+$ dscan watch
+⚠ Add @watch to your agent function. See README for usage.
+```
+
+### `dscan trail`
+
+Reads trace files and reports suspicious tool-call chains, grouped by
+severity. Exits `1` on any high or critical finding. Supports
+`--min-severity {low|medium|high|critical}` and `--json`.
+
+```text
+$ dscan trail ~/.dscan/traces/
+┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Severity ┃ Pattern         ┃ Tools Involved          ┃ Message       ┃ Confidence ┃
+┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ CRITICAL │ INJECTION_RELAY │ search_web → send_email │ untrusted...  │        85% │
+│ HIGH     │ EXFIL_SEQUENCE  │ read_file → send_email  │ read then...  │        80% │
+└──────────┴─────────────────┴─────────────────────────┴───────────────┴────────────┘
+2 findings across 5 tool calls analysed
+```
+
+### `dscan dashboard`
+
+Serves the local web UI at `localhost:4321`. `--port` sets the port;
+`--no-open` skips opening a browser.
+
+```text
+$ dscan dashboard --no-open
+✓ Dashboard at http://127.0.0.1:4321  (Ctrl-C to stop)
+```
+
+## How trail works
+
+`dscan trail` reads your trace files and looks at the order of tool
+calls, not just each call on its own. It groups calls by agent run and
+reports five kinds of suspicious sequences: reading sensitive data and
+then sending it somewhere external (exfiltration), probing for
+permissions and then running a tool the agent never declared
+(reconnaissance), pulling in untrusted web or email content and then
+immediately sending or executing (injection relay), reading several
+different sensitive sources in a row with nothing sent in between (data
+staging), and taking destructive or outbound actions that a read-only
+goal never asked for (goal drift). Each finding carries a severity and a
+confidence score so you can triage.
+
+## Contributing
+
+```bash
+git clone https://github.com/DeepScan-Security/dscan
+cd dscan
+pip install -e ".[dev]"
+pytest
+```
+
+Built test-first; coverage stays at or above 80%. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for what we need help with, and
+[SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## License
+
+MIT

dscan_security-0.1.0/README.md

@@ -0,0 +1,136 @@
+# dscan
+
+[![CI](https://github.com/DeepScan-Security/dscan/actions/workflows/ci.yml/badge.svg)](https://github.com/DeepScan-Security/dscan/actions/workflows/ci.yml)
+![coverage](https://img.shields.io/badge/coverage-97%25-brightgreen)
+[![PyPI](https://img.shields.io/pypi/v/dscan-security)](https://pypi.org/project/dscan-security/)
+[![Python](https://img.shields.io/pypi/pyversions/dscan-security)](https://pypi.org/project/dscan-security/)
+![license](https://img.shields.io/badge/license-MIT-green)
+
+An open source agent security suite. Trace and redact your agent's tool
+calls, scan its prompts and MCP configs, and detect suspicious call
+chains — then inspect everything in a local dashboard.
+
+```bash
+pip install dscan-security
+```
+
+The package installs as `dscan-security`; the import path and CLI stay
+`dscan` (`import dscan`, `dscan --help`).
+
+![dscan dashboard](docs/dashboard.png)
+
+## Quick start
+
+```python
+from dscan import watch
+
+@watch
+async def my_agent(task: str):
+    ...  # your agent code, unchanged
+```
+
+Run your agent, then open the dashboard:
+
+```bash
+dscan dashboard
+```
+
+Tool calls are written as redacted NDJSON to `~/.dscan/traces/` (override
+with `DSCAN_TRACES_DIR`). Wrapping any tool with `@watch.tool` traces its
+params and result; if you use the Anthropic SDK, `@watch` also intercepts
+`messages.create()` and traces each `tool_use` block.
+
+## What dscan catches
+
+| Capability | What it detects |
+| --- | --- |
+| `@watch` (tracing) | Every tool call — name, params, result, duration — written as redacted NDJSON; flags calls whose params contain secrets |
+| Redaction | AWS keys, Anthropic/OpenAI/GitHub/Stripe tokens, JWTs, emails, phone numbers, SSNs, Luhn-valid credit cards, database-URL passwords, high-entropy secrets |
+| `dscan scan` | Permissive prompts, injection-prone prompts, hardcoded secrets, excessive tool scope; unverified, overprivileged, and credential-leaking MCP servers |
+| `dscan trail` | Suspicious tool-call sequences across an agent run (exfiltration, recon, injection relay, data staging, goal drift) |
+| `dscan dashboard` | Local web UI: sessions, per-call timeline, redacted values, secrets flags, and trail findings |
+
+## Commands
+
+### `dscan scan`
+
+Static analysis of system prompts and MCP config files in a directory.
+Exits `1` if any high-severity issue is found.
+
+```text
+$ dscan scan ./prompts
+                                  HIGH (1)
+┏━━━━━━━┳━━━━━━━━┳━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━┓
+┃ Rule  ┃ File   ┃ Line ┃ Message                     ┃ Snippet           ┃
+┡━━━━━━━╇━━━━━━━━╇━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━┩
+│ SP003 │ sp.txt │    2 │ Hardcoded secret in prompt  │ ...sk-ant-api03... │
+└───────┴────────┴──────┴─────────────────────────────┴───────────────────┘
+✗ 1 high-severity finding(s).
+```
+
+### `dscan watch`
+
+`@watch` is a decorator, not a runtime command. This prints a reminder:
+
+```text
+$ dscan watch
+⚠ Add @watch to your agent function. See README for usage.
+```
+
+### `dscan trail`
+
+Reads trace files and reports suspicious tool-call chains, grouped by
+severity. Exits `1` on any high or critical finding. Supports
+`--min-severity {low|medium|high|critical}` and `--json`.
+
+```text
+$ dscan trail ~/.dscan/traces/
+┏━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Severity ┃ Pattern         ┃ Tools Involved          ┃ Message       ┃ Confidence ┃
+┡━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ CRITICAL │ INJECTION_RELAY │ search_web → send_email │ untrusted...  │        85% │
+│ HIGH     │ EXFIL_SEQUENCE  │ read_file → send_email  │ read then...  │        80% │
+└──────────┴─────────────────┴─────────────────────────┴───────────────┴────────────┘
+2 findings across 5 tool calls analysed
+```
+
+### `dscan dashboard`
+
+Serves the local web UI at `localhost:4321`. `--port` sets the port;
+`--no-open` skips opening a browser.
+
+```text
+$ dscan dashboard --no-open
+✓ Dashboard at http://127.0.0.1:4321  (Ctrl-C to stop)
+```
+
+## How trail works
+
+`dscan trail` reads your trace files and looks at the order of tool
+calls, not just each call on its own. It groups calls by agent run and
+reports five kinds of suspicious sequences: reading sensitive data and
+then sending it somewhere external (exfiltration), probing for
+permissions and then running a tool the agent never declared
+(reconnaissance), pulling in untrusted web or email content and then
+immediately sending or executing (injection relay), reading several
+different sensitive sources in a row with nothing sent in between (data
+staging), and taking destructive or outbound actions that a read-only
+goal never asked for (goal drift). Each finding carries a severity and a
+confidence score so you can triage.
+
+## Contributing
+
+```bash
+git clone https://github.com/DeepScan-Security/dscan
+cd dscan
+pip install -e ".[dev]"
+pytest
+```
+
+Built test-first; coverage stays at or above 80%. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for what we need help with, and
+[SECURITY.md](SECURITY.md) to report a vulnerability.
+
+## License
+
+MIT

dscan_security-0.1.0/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_security-0.1.0/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_security-0.1.0/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.
+"""