llmasm-ananya 0.4.1

LLM Attack Surface Mapper for AI Security Testing

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

LLM Attack Surface Mapper

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

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

Author: Ananya · GitHub · LinkedIn

---

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 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, 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 if you want to add a research area, write-up, or worked example.

---

Technical Quickstart

# 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)

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):

# 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

# .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
• 🐛 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.

---

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.