Metadata-Version: 2.4
Name: shadow-sniffer
Version: 0.1.0
Summary: Shadow AI detector — scans network connection logs for unsanctioned AI API/service usage and cross-references against an approved-services allowlist.
Project-URL: Homepage, https://github.com/Prasanna-27eng/shadow-sniffer
Project-URL: Repository, https://github.com/Prasanna-27eng/shadow-sniffer
Author: Prasanna Kumar Surendran
License-Expression: MIT
License-File: LICENSE
Keywords: ai-security,blue-team,cspm,data-exfiltration,network-security,purple-team,saas-security,shadow-ai
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Security
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: rich>=13.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Description-Content-Type: text/markdown

# shadow-sniffer

[![PyPI](https://img.shields.io/pypi/v/shadow-sniffer.svg)](https://pypi.org/project/shadow-sniffer/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

> Shadow AI detector — scans network connection logs for unsanctioned AI
> service usage and cross-references against an approved-services allowlist.

**Educational / authorized-use tool.** shadow-sniffer reads a local export
of outbound network connections — no live agent, packet capture, or network
access required. Use it on your own logs, or on logs you have permission to
analyze.

## Why shadow-sniffer?

Employees and AI agents routinely send data — source code, customer records,
credentials, internal documents — to third-party AI chat apps and APIs that
IT and security never approved. This is "Shadow AI": functionally the same
risk as Shadow IT, but the exfiltration channel is a chat box or an API call
that looks like normal HTTPS traffic.

shadow-sniffer is the fourth tool in the **Grassroots Expansion Pack**
(`mcp-sploit` → `prompt-fuzz` → `nhi-hunter` → `shadow-sniffer`). Where the
others attack an AI deployment's *tools*, *brain*, and *identity layer*,
shadow-sniffer looks at the *data layer* — where is data actually going.

It ships with a curated catalog of 39 known AI service domains across 8
categories (LLM Chat, LLM API, Code Assistant, Image/Video Generation, Voice
& Audio, and more), matches them against a connection log, and flags any
hit that isn't on your organization's approved list. Findings are tagged
**MITRE ATT&CK T1567 (Exfiltration Over Web Service)**.

## Quick start

```bash
pip install shadow-sniffer

shadow-sniffer scan --input connections.json --approved approved_services.json
```

## Try it without any setup

```bash
git clone https://github.com/Prasanna-27eng/shadow-sniffer
cd shadow-sniffer
pip install -e .

shadow-sniffer scan \
  --input examples/sample_connections.json \
  --approved examples/approved_services.json
```

## Connection log format

A JSON file with a `connections` list (or a bare list), or a CSV with a
header row. Recognized fields (aliases in parentheses):

| Field | Aliases |
|---|---|
| `timestamp` | `time`, `ts` |
| `src_host` | `source_host`, `hostname` |
| `src_ip` | `source_ip` |
| `user` | `username` |
| `process_name` | `process`, `proc_name` |
| `dest_host` | `dest_domain`, `destination_domain`, `remote_hostname` |
| `dest_ip` | `destination_ip`, `remote_ip` |
| `dest_port` | `destination_port`, `remote_port` |
| `bytes_sent` | `bytes_out`, `tx_bytes` |

Only `dest_host`/its aliases are matched against the AI service catalog —
shadow-sniffer does not perform DNS or reverse-DNS lookups.

## Approved-services allowlist

A JSON file with an `approved_domains` list, or a plain-text file with one
domain per line (`#` comments allowed). Domains are matched by suffix, so
`openai.com` in your allowlist covers both `api.openai.com` and
`chat.openai.com`.

## Console commands

- `shadow-sniffer scan --input <log> [--approved <allowlist>] [--output results.json]` —
  scan a connection log, print findings as a table, exit non-zero if any
  unapproved AI service usage is found (usable as a CI gate).
- `shadow-sniffer list-services` — print the full built-in AI service catalog.

## AegisTrace integration

```bash
shadow-sniffer scan --input connections.json \
  --aegistrace-url https://your-aegistrace-instance \
  --aegistrace-key $AEGISTRACE_INGEST_KEY
```

Each finding is POSTed to `/api/ingest/shadowsniffer-event`, creating an
`AgentAction` entry visible in AegisTrace's `/app/agent-security` dashboard.

## Testing

```bash
pip install -e ".[dev]"
pytest
```

## Companion projects

- [mcp-sploit](https://github.com/Prasanna-27eng/mcp-sploit) — dynamic
  security testing for MCP servers (attacks the *tools* layer)
- [prompt-fuzz](https://github.com/Prasanna-27eng/prompt-fuzz) — jailbreak
  and prompt-injection fuzzer for LLM endpoints (attacks the *brain* layer)
- [nhi-hunter](https://github.com/Prasanna-27eng/nhi-hunter) — AWS IAM
  privilege-escalation graph builder (attacks the *identity* layer)

## License

MIT — see [LICENSE](LICENSE).
