Metadata-Version: 2.4
Name: llmasm-ananya
Version: 0.4.1
Summary: LLM Attack Surface Mapper for AI Security Testing
Home-page: https://github.com/ananya/llmasm
Author: Ananya Chatterjee
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Dynamic: home-page
Dynamic: requires-python

<div align="center">

```
██╗     ██╗     ███╗   ███╗ █████╗ ███████╗███╗   ███╗
██║     ██║     ████╗ ████║██╔══██╗██╔════╝████╗ ████║
██║     ██║     ██╔████╔██║███████║███████╗██╔████╔██║
██║     ██║     ██║╚██╔╝██║██╔══██║╚════██║██║╚██╔╝██║
███████╗███████╗██║ ╚═╝ ██║██║  ██║███████║██║ ╚═╝ ██║
╚══════╝╚══════╝╚═╝     ╚═╝╚═╝  ╚═╝╚══════╝╚═╝     ╚═╝
```

### LLM Attack Surface Mapper

**A research framework for demystifying the black box of AI-powered applications.**

[![PyPI](https://img.shields.io/badge/pip-install%20llmasm-blue)](#technical-quickstart)
[![Python](https://img.shields.io/badge/python-3.10%2B-3776AB)](#technical-quickstart)
[![License](https://img.shields.io/badge/license-MIT-green)](#community--contributing)
[![SARIF](https://img.shields.io/badge/CI%2FCD-SARIF%20native-orange)](#core-features--whats-new-in-v1)
[![Status](https://img.shields.io/badge/status-research%20%26%20active%20dev-purple)](#community--contributing)

`pip install llmasm` — then run `llmasm` and you're mapping in under a minute.

**Author:** Ananya · [GitHub](https://github.com/Ananya-0306) · [LinkedIn](https://linkedin.com/in/ananya-chatterjeee)

</div>

---

## About LLMASM

Most security tools treat an AI-powered application like any other web app: crawl it, fuzz the inputs, ship a report. That approach misses what's actually interesting about these systems — the hidden `/api/internal/rag-proxy` route, the system prompt sitting in a JS bundle, the agent silently calling four tools nobody documented.

**LLMASM isn't just a bug-finder. It's a framework for understanding how AI applications are actually built.** Every scan produces a map — frameworks in use, hidden endpoints, tool/agent chains, RAG pipelines — so the output teaches you the architecture, not just a list of findings. Whether you're testing your own application or studying how modern LLM systems are assembled, LLMASM is built to make that structure visible.

> **In short:** LLMASM treats AI applications as attack surfaces worth understanding — not black boxes worth fearing.

This is a defensive, educational tool for applications **you own or are explicitly authorized to test.** See [Ethical & Responsible Use](#ethical--responsible-use) before you point it at anything.

---

## Core Features — What's New in V1

| Feature | What it does |
|---|---|
| 🧩 **AST Semantic Agent Graph Mapper** | Parses application source with AST analysis to reconstruct the full agent/tool call graph — not just *that* a tool exists, but how it's wired to other components and what it can reach |
| 🕵️ **Shadow API Fuzzer** | Actively probes discovered internal/hidden endpoints (RAG proxies, internal inference routes) that never appear in public API docs |
| 📂 **Local Source Code Scan** | `llmasm source` runs the AST semantic parser directly against a local codebase — no live target required, ideal for pre-deployment review |
| 📑 **API Spec Ingestion** | `llmasm api` ingests an OpenAPI or Postman JSON spec to map and fuzz AI-related endpoints without needing to crawl or intercept traffic |
| 🔁 **DevSecOps / SARIF Integration** | Native SARIF export drops findings straight into GitHub Code Scanning or GitLab security dashboards — built for continuous testing, not one-off audits |
| ⚖️ **LLM-as-a-Judge Verification** | A secondary model reviews evidence (responses, runtime state) before anything is marked as a finding — flagged for human review, never auto-confirmed |

Combined with static bundle analysis and runtime interception, LLMASM reconstructs what's actually running behind the chat UI — framework, endpoints, tool definitions, and pipeline — end to end.

---

## Learning Path — For Researchers & Students

LLMASM doubles as a guided entry point into AI security research. If you're new to this space, each area below is a productive place to start digging — run a scan, then go read the underlying concept:

- 🎯 **Prompt Injection & System Prompt Leakage** — how instructions meant to stay server-side end up recoverable from the client or the model's own output
- 🕸️ **Agentic Blast Radius** — once an agent can call tools, how far can a single compromised input actually reach?
- ☣️ **RAG Poisoning & Context Leakage** — what happens when the retrieval layer itself becomes an untrusted input
- 🔍 **Hidden AI APIs & Shadow Endpoints** — the internal surface that exists between "what's documented" and "what's actually running"

> 💡 **Suggested workflow:** scan a staging app you control, read the corresponding section in [OWASP Top 10 for LLM Applications](https://owasp.org/www-project-top-10-for-large-language-model-applications/), then compare what LLMASM surfaced against what the framework predicts. That gap is usually where the learning happens.

We'd love for this section to grow — see [Community & Contributing](#community--contributing) if you want to add a research area, write-up, or worked example.

---

## Technical Quickstart

```bash
# 1. Clone the repository
git clone https://github.com/ananya/llmasm
cd llmasm

# 2. Install Python dependencies
pip install -r requirements.txt

# 3. Install Playwright browser binaries (required for dynamic interception)
playwright install

# 4. Install LLMASM as a CLI
pip install -e .
```

### Interactive mode (recommended for first run)

```bash
llmasm
```

```
LLM Attack Surface Mapper — v1.0
Author: Ananya | GitHub: github.com/Ananya-0306 | LinkedIn: linkedin.com/in/ananya-chatterjee

──────────────── Interactive Framework ────────────────
Select from the menu:

  1) Web Application AI Scan      (HTML report only)
  2) DevSecOps Pipeline Scan      (SARIF export + HTML report)
  3) Local Source Code Scan       (AST semantic parser)
  4) API Spec Ingestion           (OpenAPI / Postman JSON)
  99) Exit the LLMASM Framework

llmasm > [1/2/3/4/99]:
```

### CLI / CI mode

LLMASM provides three primary modes of operation via the CLI, each a distinct subcommand rather than a flag — `scan`, `source`, and `api` reflect fundamentally different detection methodologies (dynamic, static, and spec-driven fuzzing):

```bash
# 1. Web application scan — map a live AI web app's attack surface
llmasm scan https://your-staging-app.example.com --sarif

# Authenticated scan with SARIF export for CI/CD
llmasm scan https://your-staging-app.example.com --auth "Bearer xyz123" --sarif

# 2. Local source code scan — AST parser for hardcoded prompts, agentic
#    chains, and framework signatures (no live target required)
llmasm source ./path/to/project --sarif

# 3. API specification fuzzing — ingest an OpenAPI/Postman JSON spec
#    and fuzz the AI backend directly
llmasm api swagger.json --sarif
```

### CI/CD integration

```yaml
# .github/workflows/llmasm.yml
- name: LLMASM scan
  run: llmasm scan ${{ secrets.STAGING_URL }} --sarif
- uses: github/codeql-action/upload-sarif@v3
  with:
    sarif_file: llmasm_report.sarif
```

### Example output

```
╭─────────────────────── LLMASM SCAN ───────────────────────╮
│ Target: https://staging.your-ai-app.example.com            │
╰──────────────────────────────────────────────────────────╯
[*] [STATIC] Launching AST agent graph mapper...
[+] [STATIC] Found 3 structural AI signatures (LangChain, RAG layer)

[*] [DYNAMIC] Launching Shadow API fuzzer...
[+] [DYNAMIC] Captured 12 internal API calls

[*] [VERIFY] Reviewing candidate findings with LLM judge...
[+] [VERIFY] 2 findings confirmed, flagged for human review

[+] HTML report:  llmasm_report.html
[+] SARIF export: llmasm_report.sarif
```

---

## Ethical & Responsible Use

> ⚠️ **LLMASM is built strictly for authorized testing and educational use.** It is not a tool for unauthorized access, and it should never be pointed at a system you don't own or aren't explicitly permitted to test.

LLMASM is intended for:

- ✅ Authorized security testing of your own applications
- ✅ Engagements with documented, written authorization
- ✅ Academic and security research in controlled environments
- ✅ Bug bounty programs, strictly within the program's defined scope

**Do not scan systems you don't own or don't have explicit written permission to test.** Running this against third-party production systems without authorization may violate computer-crime law in your jurisdiction (e.g. the CFAA in the US) regardless of intent. The maintainers assume no liability for misuse.

---

## Community & Contributing

LLMASM is meant to grow as a collaborative research environment, not just a codebase. Contributions of all kinds are welcome:

- 🧠 New detection modules or analyzers
- 📚 Research write-ups, worked examples, or additions to the [Learning Path](#learning-path--for-researchers--students)
- 🐛 Bug fixes, report improvements, or documentation
- 🔧 DevSecOps integrations for other CI/CD platforms

Please read `CONTRIBUTING.md` before opening a pull request. First-time contributors and students are explicitly welcome — if you're not sure where to start, open an issue and ask.

### Security reporting

Found a vulnerability in LLMASM itself? Please follow the responsible disclosure process in `SECURITY.md` rather than filing a public issue.

---

<div align="center">

**AI applications aren't black boxes. They're architectures waiting to be understood — map them responsibly.**

⭐ If LLMASM helped you learn something or saved you time, consider starring the repo.

</div>
