AASRT/README.md

🛡️ AASRT

AI Agent Security Reconnaissance Tool

Imperial Security Reconnaissance System for AI Agent Discovery

---

🎯 Overview

AASRT (AI Agent Security Reconnaissance Tool) automates the discovery of publicly exposed AI agent implementations—including ClawdBot, AutoGPT, LangChain agents, Jupyter notebooks, and more—using the Shodan search engine API.

As organizations rapidly deploy AI agents and LLM-powered systems, many are inadvertently exposed to the public internet without proper security controls. AASRT helps security teams identify these exposures through passive reconnaissance before attackers do.

Key Value Propositions:

• 🔍 Automated Discovery — Find exposed AI infrastructure across the internet
• ⚠️ Vulnerability Assessment — Automatic detection of API key leaks, auth issues, and dangerous functionality
• 📊 Risk Scoring — CVSS-based scoring with severity categorization (Critical/High/Medium/Low)
• 📋 Comprehensive Reporting — JSON, CSV exports with persistent scan history

Target Audience: Security researchers, penetration testers, DevSecOps teams, and compliance officers conducting authorized security assessments.

---

✨ Features

Feature	Description
🔍 Multi-Source Search	Shodan integration (Censys/BinaryEdge planned)
🛡️ Vulnerability Assessment	Detects API key exposure, auth issues, debug mode, SSL problems
📊 Risk Scoring	CVSS-based 0-10 scoring with severity levels
📋 13+ Query Templates	Pre-built searches for AutoGPT, LangChain, Jupyter, and more
🌐 Web Dashboard	Interactive Streamlit UI with Star Wars Imperial theme
⌨️ Full CLI	Complete command-line interface for automation
💾 Scan History	SQLite database for persistent findings (2,253+ findings tracked)
🗺️ Threat Mapping	Interactive 3D globe visualization of discovered targets
🐳 Docker Ready	Multi-stage Dockerfile with docker-compose for easy deployment
✅ Production Ready	63 passing tests, comprehensive input validation, retry logic

---

📦 Installation

Prerequisites

• Python 3.11+ (tested on 3.13)
• pip package manager
• Shodan API Key — Get one here

Method 1: From Source (Recommended)

# Clone the repository
git clone https://github.com/yourusername/aasrt.git
cd aasrt

# Install dependencies
pip install -r requirements.txt

# (Optional) Install development dependencies
pip install -r requirements-dev.txt

Method 2: Using pip (When Published)

pip install aasrt

Method 3: Docker

# Build and run with Docker Compose
docker-compose up -d

# Or build manually
docker build -t aasrt .
docker run -e SHODAN_API_KEY=your_key aasrt

Configuration

1. Create environment file:

   cp .env.example .env
   

2. Add your Shodan API key:

   # .env
   SHODAN_API_KEY=your_shodan_api_key_here
   

3. (Optional) Customize settings in config.yaml:

   shodan:
     rate_limit: 1      # Queries per second
     max_results: 100   # Results per query
     timeout: 30        # Request timeout
   

---

🚀 Quick Start

Example 1: Run a Template Scan (CLI)

python -m src.main scan --template clawdbot_instances --yes

Example 2: Launch Web Dashboard

streamlit run app.py
# Open http://localhost:8501 in your browser

Example 3: Custom Shodan Query

python -m src.main scan --query 'http.title:"AutoGPT"' --yes

Example 4: View Scan History

python -m src.main history

Example 5: List Available Templates

python -m src.main templates

Output:

┌─────────────────────────────┬──────────┐
│ Template Name               │ Queries  │
├─────────────────────────────┼──────────┤
│ autogpt_instances           │ 2 queries│
│ clawdbot_instances          │ 3 queries│
│ langchain_agents            │ 2 queries│
│ jupyter_notebooks           │ 3 queries│
│ exposed_env_files           │ 2 queries│
│ ...                         │ ...      │
└─────────────────────────────┴──────────┘

---

📋 Available Query Templates

Template	Target	Queries
clawdbot_instances	ClawdBot AI dashboards	5
autogpt_instances	AutoGPT deployments	5
langchain_agents	LangChain agent implementations	5
openai_exposed	Exposed OpenAI integrations	2
exposed_env_files	Leaked .env configuration files	2
debug_mode	Services with debug mode enabled	3
jupyter_notebooks	Exposed Jupyter notebooks	3
streamlit_apps	Streamlit applications	2
ai_dashboards	Generic AI/LLM dashboards	3
clawsec_advisories	ClawSec CVE-matched targets	10

Create custom templates: See Custom Query Templates Guide

---

📖 Documentation

Document	Description
📖 Quick Start Guide	Detailed usage instructions and examples
📋 Custom Query Templates	Create your own Shodan query templates
🗺️ Map Visualization Guide	Interactive threat map features

Developer Documentation (in dev/docs/):

Document	Description
📊 Project Status	Current system health and statistics
📝 Technical Specification	Full product requirements document
🔧 Bug Fixes Log	Technical details of resolved issues
🗺️ Map Enhancements	Map visualization implementation details

---

⚠️ Legal Disclaimer

🚨 IMPORTANT: This tool is for AUTHORIZED SECURITY RESEARCH and DEFENSIVE PURPOSES ONLY.

Unauthorized access to computer systems is ILLEGAL under:

• 🇺🇸 CFAA (Computer Fraud and Abuse Act) — United States
• 🇬🇧 Computer Misuse Act — United Kingdom
• 🇪🇺 EU Directive on Attacks Against Information Systems
• Similar laws exist in virtually every jurisdiction worldwide

By using this tool, you acknowledge and agree that:

1. ✅ You have explicit authorization to scan target systems
2. ✅ You will comply with all applicable laws and terms of service
3. ✅ You will responsibly disclose any vulnerabilities discovered
4. ✅ You will NOT exploit discovered vulnerabilities
5. ✅ You understand this tool performs passive reconnaissance only

The authors assume NO LIABILITY for misuse of this tool.

---

📁 Project Structure

aasrt/
├── src/                      # Core application code
│   ├── main.py               # CLI entry point
│   ├── core/                 # Query manager, risk scorer, vulnerability assessor
│   ├── engines/              # Search engine integrations (Shodan)
│   ├── enrichment/           # Threat intelligence (ClawSec feed)
│   ├── reporting/            # JSON/CSV report generators
│   ├── storage/              # SQLite database layer
│   └── utils/                # Config, logging, validators, exceptions
├── queries/                  # Query template YAML files
├── reports/                  # Generated scan reports
├── logs/                     # Application logs
├── data/                     # SQLite database
├── dev/                      # Development files (not for production)
│   ├── tests/                # Unit and integration tests (63 tests)
│   ├── docs/                 # Developer documentation
│   ├── pytest.ini            # Pytest configuration
│   └── requirements-dev.txt  # Development dependencies
├── app.py                    # Streamlit web dashboard
├── config.yaml               # Application configuration
├── requirements.txt          # Production dependencies
├── Dockerfile                # Multi-stage Docker build
└── docker-compose.yml        # Docker Compose with PostgreSQL

---

🧪 Testing

# Run all unit tests (from project root)
python -m pytest dev/tests/unit/ -v

# Run with coverage
python -m pytest dev/tests/unit/ --cov=src --cov-report=term-missing

# Run specific test module
python -m pytest dev/tests/unit/test_validators.py -v

# Use pytest.ini config
python -m pytest -c dev/pytest.ini dev/tests/unit/ -v

Current Status: 63 tests passing, 35% coverage

---

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

For bugs or feature requests, please open an issue.

---

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

---

🙏 Acknowledgments

• Shodan — Search engine for internet-connected devices
• Streamlit — Web dashboard framework
• SQLAlchemy — Database ORM
• Click — CLI framework
• Rich — Terminal formatting
• The security research community

---

⭐ Star this repo if you find it useful!

May the Force be with your reconnaissance. 🌟