AASRT/QUICK_START.md

AASRT Quick Start Guide

Prerequisites

✅ Python 3.13 installed ✅ All dependencies installed (pip install -r requirements.txt) ✅ Shodan API key configured in .env file

Basic Commands

1. Check System Status

python -m src.main status

This shows:

• Shodan API status and credits
• Available query templates (13 templates)
• Your current plan type

2. List Available Templates

python -m src.main templates

Available templates:

• clawdbot_instances - Find ClawdBot dashboards
• autogpt_instances - Find AutoGPT deployments
• langchain_agents - Find LangChain agents
• openai_exposed - Find exposed OpenAI integrations
• exposed_env_files - Find exposed .env files
• debug_mode - Find services with debug mode enabled
• jupyter_notebooks - Find exposed Jupyter notebooks
• streamlit_apps - Find Streamlit applications
• And 5 more...

3. Run a Scan

Using a template (recommended):

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

Using a custom query:

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

Without --yes flag (shows legal disclaimer):

python -m src.main scan --template clawdbot_instances

4. View Scan History

python -m src.main history

Shows:

• Last 10 scans
• Scan IDs, timestamps, results count
• Database statistics

5. Generate Report from Previous Scan

python -m src.main report --scan-id <scan_id>

Understanding Scan Results

Console Output

+-------------------------------- Scan Summary --------------------------------+
| Scan ID: 211a5df0...                                                         |
| Duration: 3.3s                                                               |
| Total Results: 32                                                            |
| Average Risk Score: 3.7/10                                                   |
+------------------------------------------------------------------------------+

 Risk Distribution  
+------------------+
| Severity | Count |
|----------+-------|
| Critical |     4 |
| High     |     0 |
| Medium   |     0 |
| Low      |    28 |
+------------------+

Report Files

Reports are saved in ./reports/ directory:

• JSON format: scan_<id>_<timestamp>.json
• CSV format: scan_<id>_<timestamp>.csv (if enabled)

Database

All scans are automatically saved to: ./data/scanner.db

Common Use Cases

1. Find Exposed AI Dashboards

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

2. Find Debug Mode Enabled Services

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

3. Find Exposed Environment Files

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

4. Custom Search for Specific Service

python -m src.main scan --query 'product:"nginx" port:8080' --yes

Understanding Risk Scores

• 10.0 (Critical): No authentication on sensitive dashboards
• 7.0-9.9 (High): Exposed API keys, shell access, database strings
• 5.0-6.9 (Medium): SSL issues, exposed config files
• 3.0-4.9 (Low): Self-signed certificates, missing security.txt
• 1.0-2.9 (Info): Informational findings

Vulnerability Types Detected

1. Authentication Issues

   • No authentication on dashboards
   • Missing security controls

2. API Key Exposure

   • OpenAI keys (sk-...)
   • Anthropic keys (sk-ant-...)
   • AWS credentials (AKIA...)
   • GitHub tokens (ghp_...)
   • Google API keys (AIza...)
   • Stripe keys (sk_live_...)

3. Dangerous Functionality

   • Shell execution endpoints
   • Debug mode enabled
   • File upload functionality
   • Admin panels exposed
   • Database connection strings

4. Information Disclosure

   • Exposed .env files
   • Configuration files
   • Git repositories
   • Source code files

5. SSL/TLS Issues

   • Expired certificates
   • Self-signed certificates
   • No SSL on HTTPS ports

Configuration

Edit config.yaml to customize:

shodan:
  rate_limit: 1  # queries per second
  max_results: 100

vulnerability_checks:
  enabled: true
  passive_only: true

reporting:
  formats:
    - json
    - csv
  output_dir: "./reports"

filtering:
  min_confidence_score: 70
  exclude_honeypots: true

logging:
  level: "INFO"
  file: "./logs/scanner.log"

Tips & Best Practices

1. Start with specific templates rather than broad queries
2. Use --yes flag to skip legal disclaimer for automated scans
3. Check your Shodan credits before running large scans
4. Review reports in JSON format for detailed findings
5. Use scan history to track your reconnaissance over time

Troubleshooting

"Invalid API key" error

• Check your .env file has the correct SHODAN_API_KEY
• Verify the key is valid at https://account.shodan.io/

"Rate limit exceeded"

• Reduce rate_limit in config.yaml
• Wait a few minutes before retrying

No results found

• Try different templates or queries
• Check if the service/product exists on Shodan
• Use python -m src.main status to verify API connectivity

Legal Notice

⚠️ Important: This tool is for authorized security research only.

• Only scan systems you have permission to test
• Comply with all applicable laws and terms of service
• Responsibly disclose any findings
• Do not exploit discovered vulnerabilities

Support

• Documentation: See README.md and Outline.md
• Bug Fixes: See FIXES_APPLIED.md
• Query Templates: Check queries/ directory
• Logs: Check logs/scanner.log for detailed information

Current Status

✅ All systems operational ✅ 13 query templates available ✅ 81 Shodan query credits remaining ✅ Database with 17 scans and 2253 findings ✅ All bug fixes applied and tested