# π‘οΈ AASRT
### AI Agent Security Reconnaissance Tool
*Imperial Security Reconnaissance System for AI Agent Discovery*
[](https://www.python.org/)
[](LICENSE)
[](PROJECT_STATUS.md)
[](https://github.com/yourusername/aasrt/releases)
[](tests/)
[](tests/)
---
## π― 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](https://account.shodan.io/)
### Method 1: From Source (Recommended)
```bash
# 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)
```bash
pip install aasrt
```
### Method 3: Docker
```bash
# 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:**
```bash
cp .env.example .env
```
2. **Add your Shodan API key:**
```bash
# .env
SHODAN_API_KEY=your_shodan_api_key_here
```
3. **(Optional) Customize settings in `config.yaml`:**
```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)
```bash
python -m src.main scan --template clawdbot_instances --yes
```
### Example 2: Launch Web Dashboard
```bash
streamlit run app.py
# Open http://localhost:8501 in your browser
```
### Example 3: Custom Shodan Query
```bash
python -m src.main scan --query 'http.title:"AutoGPT"' --yes
```
### Example 4: View Scan History
```bash
python -m src.main history
```
### Example 5: List Available Templates
```bash
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](CUSTOM_QUERIES_GUIDE.md)
---
## π Documentation
| Document | Description |
|----------|-------------|
| π [Quick Start Guide](QUICK_START.md) | Detailed usage instructions and examples |
| π [Custom Query Templates](CUSTOM_QUERIES_GUIDE.md) | Create your own Shodan query templates |
| πΊοΈ [Map Visualization Guide](QUICK_MAP_GUIDE.md) | Interactive threat map features |
**Developer Documentation** (in `dev/docs/`):
| Document | Description |
|----------|-------------|
| π [Project Status](dev/docs/PROJECT_STATUS.md) | Current system health and statistics |
| π [Technical Specification](dev/docs/Outline.md) | Full product requirements document |
| π§ [Bug Fixes Log](dev/docs/FIXES_APPLIED.md) | Technical details of resolved issues |
| πΊοΈ [Map Enhancements](dev/docs/MAP_ENHANCEMENTS.md) | 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
```bash
# 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](https://github.com/yourusername/aasrt/issues).
---
## π License
This project is licensed under the **MIT License** β see the [LICENSE](LICENSE) file for details.
---
## π Acknowledgments
- [Shodan](https://www.shodan.io/) β Search engine for internet-connected devices
- [Streamlit](https://streamlit.io/) β Web dashboard framework
- [SQLAlchemy](https://www.sqlalchemy.org/) β Database ORM
- [Click](https://click.palletsprojects.com/) β CLI framework
- [Rich](https://rich.readthedocs.io/) β Terminal formatting
- The security research community
---
**β Star this repo if you find it useful!**
*May the Force be with your reconnaissance.* π