Skip to content

Commit ad2f921

Browse files
h0tak88rh0tak88r
committed
feat: comprehensive README update and cleanup
- Updated README.md with complete feature documentation - Added detailed installation and usage instructions - Removed test files and debug statements - Cleaned up codebase for production release - Added comprehensive Discord command documentation - Included advanced usage examples and configuration guide
1 parent 23d7f34 commit ad2f921

4 files changed

Lines changed: 270 additions & 66 deletions

File tree

‎README.md‎

Lines changed: 270 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,85 +1,313 @@
1-
# AutoAR (Modular) – Discord + CLI
1+
# AutoAR (Automated Attack Reconnaissance) 🚀
22

3-
AutoAR is a modular security automation toolkit with a Discord bot frontend and a bash-based CLI backend. The system streams findings to Discord via a webhook and supports Dokploy deployments via Docker.
3+
AutoAR is a comprehensive, modular security automation toolkit designed for bug bounty hunters, penetration testers, and security researchers. It combines a Discord bot frontend with a powerful bash-based CLI backend, providing automated reconnaissance, vulnerability scanning, and attack surface analysis.
44

5-
## Quick Start (Docker Compose)
5+
## ✨ Features
66

7-
1) Set environment (required):
7+
### 🔍 **Reconnaissance & Discovery**
8+
- **Subdomain Enumeration**: Multiple engines (Subfinder, Amass, Assetfinder, etc.)
9+
- **Live Host Detection**: Fast HTTP/HTTPS validation with custom timeouts
10+
- **CNAME Analysis**: CNAME record extraction and analysis
11+
- **URL Collection**: Comprehensive URL gathering from multiple sources
12+
- **Technology Detection**: Web technology stack identification
13+
- **DNS Takeover Detection**: Comprehensive DNS takeover vulnerability scanning
814

9-
- DISCORD_BOT_TOKEN: Bot token
10-
- DISCORD_WEBHOOK: Channel webhook for logs/files
15+
### 🛡️ **Vulnerability Scanning**
16+
- **Nuclei Integration**: 1000+ vulnerability templates with custom rate limiting
17+
- **WordPress Plugin Confusion**: Automated WP plugin/theme confusion attack detection
18+
- **Dependency Confusion**: GitHub repository dependency confusion scanning
19+
- **S3 Bucket Enumeration**: AWS S3 bucket discovery and analysis
20+
- **SQL Injection Testing**: SQLMap integration for automated SQLi testing
21+
- **XSS Detection**: Dalfox integration for cross-site scripting detection
22+
- **Backup File Discovery**: Automated backup file and sensitive file discovery
1123

12-
Optionally set API keys (SecurityTrails, etc.) in `.env`.
24+
### 🎯 **Specialized Scanners**
25+
- **JavaScript Analysis**: JS file collection and secret extraction
26+
- **GitHub Reconnaissance**: Organization and repository scanning
27+
- **Port Scanning**: Nmap integration for port discovery
28+
- **Reflection Testing**: HTTP parameter reflection analysis
29+
- **Gf Pattern Matching**: Custom pattern matching for various vulnerabilities
1330

14-
2) Build and run:
31+
### 🤖 **Discord Integration**
32+
- **Real-time Notifications**: Live scan progress and results
33+
- **File Sharing**: Automatic result file uploads
34+
- **Slash Commands**: Easy-to-use Discord commands
35+
- **Progress Tracking**: Real-time scan status updates
1536

37+
### 🗄️ **Database Support**
38+
- **PostgreSQL Integration**: Full database support for results storage
39+
- **SQLite Fallback**: Lightweight database option
40+
- **Data Export**: Easy data export and analysis
41+
- **Result Management**: Organized result storage and retrieval
42+
43+
## 🚀 Quick Start
44+
45+
### Docker Compose (Recommended)
46+
47+
1. **Clone the repository**:
48+
```bash
49+
git clone https://github.com/yourusername/AutoAR.git
50+
cd AutoAR
51+
```
52+
53+
2. **Set up environment variables**:
54+
```bash
55+
cp env.example .env
56+
# Edit .env with your configuration
57+
```
58+
59+
3. **Required Environment Variables**:
60+
```bash
61+
DISCORD_BOT_TOKEN=your_discord_bot_token
62+
DISCORD_WEBHOOK=your_discord_webhook_url
63+
```
64+
65+
4. **Optional API Keys** (for enhanced functionality):
66+
```bash
67+
SECURITYTRAILS_API_KEY=your_key
68+
SHODAN_API_KEY=your_key
69+
VIRUSTOTAL_API_KEY=your_key
70+
GITHUB_TOKEN=your_token
71+
# ... and many more (see docker-compose.yml for full list)
72+
```
73+
74+
5. **Build and run**:
1675
```bash
17-
# full toolchain baked in by default
1876
docker compose build
1977
docker compose up -d
2078
```
2179

22-
3) Bot will start and register slash commands. Use commands like:
80+
6. **Verify installation**:
81+
```bash
82+
docker logs autoar-bot
83+
```
84+
85+
### Manual Installation
86+
87+
1. **Install dependencies**:
88+
```bash
89+
# Python dependencies
90+
pip install -r requirements.txt
91+
92+
# System dependencies (Ubuntu/Debian)
93+
sudo apt update
94+
sudo apt install -y subfinder amass assetfinder httpx nuclei nmap sqlmap dalfox ffuf gobuster dirb dirbuster wafw00f whatweb wpscan nikto masscan naabu naabu-probe httpx-probe
95+
96+
# Additional tools
97+
go install -v github.com/projectdiscovery/subfinder/v2/cmd/subfinder@latest
98+
go install -v github.com/projectdiscovery/httpx/cmd/httpx@latest
99+
go install -v github.com/projectdiscovery/nuclei/v2/cmd/nuclei@latest
100+
```
101+
102+
2. **Configure the system**:
103+
```bash
104+
chmod +x *.sh modules/*.sh
105+
cp env.example .env
106+
# Edit .env with your configuration
107+
```
108+
109+
3. **Run the Discord bot**:
110+
```bash
111+
python discord_bot.py
112+
```
23113

24-
- /subdomains domain:example.com
25-
- /domain_run domain:example.com
114+
## 📖 Usage
26115

27-
## CLI Usage (inside container)
116+
### Discord Commands
117+
118+
Once the bot is running, use these slash commands in Discord:
119+
120+
#### Basic Reconnaissance
121+
- `/subdomains domain:example.com` - Enumerate subdomains
122+
- `/livehosts domain:example.com` - Find live hosts
123+
- `/cnames domain:example.com` - Extract CNAME records
124+
- `/urls domain:example.com` - Collect URLs
125+
- `/tech domain:example.com` - Detect technologies
126+
127+
#### Vulnerability Scanning
128+
- `/nuclei domain:example.com` - Run Nuclei scans
129+
- `/wpdepconf domain:example.com` - WordPress plugin confusion
130+
- `/dalfox domain:example.com` - XSS detection
131+
- `/sqlmap domain:example.com` - SQL injection testing
132+
- `/backup domain:example.com` - Backup file discovery
133+
134+
#### Specialized Scans
135+
- `/js domain:example.com` - JavaScript analysis
136+
- `/github org:company` - GitHub reconnaissance
137+
- `/s3 bucket:example-bucket` - S3 bucket scanning
138+
- `/dns domain:example.com` - DNS takeover detection
139+
- `/ports domain:example.com` - Port scanning
140+
141+
#### Workflows
142+
- `/lite domain:example.com` - Light reconnaissance
143+
- `/fastlook domain:example.com` - Quick scan
144+
- `/domain domain:example.com` - Full domain analysis
145+
146+
### CLI Usage
147+
148+
Access the container and use the CLI directly:
28149

29150
```bash
30-
# Exec into the container
151+
# Enter the container
31152
docker exec -it autoar-bot bash
32153

33-
# Examples
154+
# Basic reconnaissance
34155
/app/main.sh subdomains get -d example.com
35-
/app/main.sh cnames get -d example.com
36156
/app/main.sh livehosts get -d example.com
157+
/app/main.sh cnames get -d example.com
37158
/app/main.sh urls collect -d example.com
38-
/app/main.sh reflection scan -d example.com
159+
160+
# Vulnerability scanning
39161
/app/main.sh nuclei run -d example.com
40-
/app/main.sh ports scan -d example.com
41-
/app/main.sh gf scan -d example.com
42-
/app/main.sh sqlmap run -d example.com
162+
/app/main.sh wpDepConf scan -d example.com
43163
/app/main.sh dalfox run -d example.com
164+
/app/main.sh sqlmap run -d example.com
165+
166+
# Specialized scans
167+
/app/main.sh js scan -d example.com
168+
/app/main.sh github scan -r owner/repo
169+
/app/main.sh s3 scan -b bucket-name
44170
/app/main.sh dns takeover -d example.com
171+
172+
# Workflows
45173
/app/main.sh lite run -d example.com
174+
/app/main.sh fastlook run -d example.com
46175
/app/main.sh domain run -d example.com
47176

48-
# DB helpers (SQLite)
177+
# Database operations
49178
/app/main.sh db domains list
50179
/app/main.sh db subdomains list -d example.com
51-
/app/main.sh db subdomains export -d example.com -o /app/new-results/example.com/subs/db-subdomains.txt
180+
/app/main.sh db subdomains export -d example.com -o results.txt
52181
```
53182

54-
## Configuration
183+
## 🔧 Configuration
184+
185+
### Environment Variables
186+
187+
| Variable | Description | Default |
188+
|----------|-------------|---------|
189+
| `DISCORD_BOT_TOKEN` | Discord bot token | Required |
190+
| `DISCORD_WEBHOOK` | Discord webhook URL | Required |
191+
| `DISCORD_ONLY` | Discord-only mode (no local files) | `false` |
192+
| `SAVE_TO_DB` | Save results to database | `true` |
193+
| `DB_TYPE` | Database type (postgresql/sqlite) | `postgresql` |
194+
| `DB_HOST` | Database host | Required for PostgreSQL |
195+
| `VERBOSE` | Verbose logging | `true` |
196+
197+
### API Keys
198+
199+
Configure these for enhanced functionality:
200+
201+
- **SecurityTrails**: `SECURITYTRAILS_API_KEY`
202+
- **Shodan**: `SHODAN_API_KEY`
203+
- **VirusTotal**: `VIRUSTOTAL_API_KEY`
204+
- **GitHub**: `GITHUB_TOKEN`
205+
- **AWS**: `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`
206+
- **And 20+ more** (see docker-compose.yml)
207+
208+
### Customization
209+
210+
- **Nuclei Templates**: Place custom templates in `nuclei_templates/`
211+
- **Wordlists**: Add custom wordlists to `Wordlists/`
212+
- **Regex Patterns**: Customize patterns in `regexes/`
213+
- **Rate Limits**: Adjust `NUCLEI_RATE_LIMIT` and `NUCLEI_CONCURRENCY`
214+
215+
## 📁 Project Structure
216+
217+
```
218+
AutoAR/
219+
├── modules/ # Core scanning modules
220+
│ ├── subdomains.sh # Subdomain enumeration
221+
│ ├── livehosts.sh # Live host detection
222+
│ ├── nuclei.sh # Nuclei integration
223+
│ ├── wp_plugin_confusion.sh # WordPress scanning
224+
│ └── ... # Other modules
225+
├── python/ # Python utilities
226+
│ ├── discord_bot.py # Discord bot
227+
│ ├── db_handler.py # Database operations
228+
│ └── wp_update_confusion.py # WP confusion scanner
229+
├── lib/ # Shared libraries
230+
│ ├── logging.sh # Logging utilities
231+
│ ├── utils.sh # Common utilities
232+
│ └── discord.sh # Discord integration
233+
├── nuclei_templates/ # Nuclei vulnerability templates
234+
├── Wordlists/ # Wordlists and patterns
235+
├── regexes/ # Custom regex patterns
236+
├── docker-compose.yml # Docker configuration
237+
├── Dockerfile # Container definition
238+
└── main.sh # CLI entry point
239+
```
240+
241+
## 🛠️ Advanced Usage
242+
243+
### Custom Workflows
244+
245+
Create custom scanning workflows by combining modules:
55246

56-
- Config file: `/app/autoar.yaml` (generated at startup by `generate_config.sh` using env)
57-
- Key env vars: `DISCORD_ONLY`, `DISCORD_WEBHOOK`, `AUTOAR_RESULTS_DIR`, `AUTOAR_CONFIG_FILE`
58-
- Results path: `/app/new-results` (volume `results-data`)
247+
```bash
248+
# Custom reconnaissance workflow
249+
/app/main.sh subdomains get -d example.com
250+
/app/main.sh livehosts get -d example.com
251+
/app/main.sh urls collect -d example.com
252+
/app/main.sh nuclei run -d example.com
253+
/app/main.sh dalfox run -d example.com
254+
```
59255

60-
## Build Variants
256+
### Database Management
61257

62-
- RUN_SETUP_AT_BUILD=true: Bake full toolchain (default in compose)
63-
- RUN_FASTLOOK_SETUP=true: Minimal install for fastLook verification
258+
```bash
259+
# List all domains
260+
/app/main.sh db domains list
64261

65-
## Healthcheck
262+
# Export subdomains for a domain
263+
/app/main.sh db subdomains export -d example.com -o subdomains.txt
66264

67-
Container reports healthy if `discord` python module loads. The bot logs startup to stdout.
265+
# Clean up old data
266+
/app/main.sh cleanup run --domain example.com
267+
```
68268

69-
## Develop Branch Workflow
269+
### Batch Processing
70270

71271
```bash
72-
git checkout -b develop
73-
# add/commit changes
74-
git add -A && git commit -m "feat: modular db module and discord slash cmds"
75-
# set upstream once
76-
git push -u origin develop
272+
# Process multiple domains from a file
273+
while read domain; do
274+
/app/main.sh domain run -d "$domain"
275+
done < domains.txt
77276
```
78277

79-
Dokploy should be configured to track the `develop` branch or a specific tag. Ensure `docker-compose.yml` is at repo root (as provided).
278+
## 🔒 Security Considerations
279+
280+
- **API Keys**: Store sensitive API keys in environment variables
281+
- **Rate Limiting**: Respect API rate limits to avoid service disruption
282+
- **Legal Compliance**: Ensure you have permission to scan target domains
283+
- **Data Privacy**: Be mindful of sensitive data in scan results
284+
285+
## 🤝 Contributing
286+
287+
1. Fork the repository
288+
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
289+
3. Commit your changes (`git commit -m 'Add amazing feature'`)
290+
4. Push to the branch (`git push origin feature/amazing-feature`)
291+
5. Open a Pull Request
292+
293+
## 📝 License
294+
295+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
296+
297+
## 🙏 Acknowledgments
298+
299+
- [ProjectDiscovery](https://projectdiscovery.io/) for amazing tools
300+
- [Nuclei](https://nuclei.projectdiscovery.io/) for vulnerability templates
301+
- [Subfinder](https://github.com/projectdiscovery/subfinder) for subdomain enumeration
302+
- [Httpx](https://github.com/projectdiscovery/httpx) for HTTP probing
303+
- All the open-source security tools that make this project possible
304+
305+
## 📞 Support
306+
307+
- **Issues**: [GitHub Issues](https://github.com/yourusername/AutoAR/issues)
308+
- **Discussions**: [GitHub Discussions](https://github.com/yourusername/AutoAR/discussions)
309+
- **Discord**: Join our Discord server for real-time support
80310

81-
## Notes
311+
---
82312

83-
- Some modules skip gracefully if a tool is missing; run `setup.sh` or bake tools at build.
84-
- In DISCORD_ONLY=true, files sent to Discord may be deleted locally after upload.
85-
- `modules/db.sh` requires `sqlite3` binary available in the runtime (install if needed).
313+
**⚠️ Disclaimer**: This tool is for educational and authorized testing purposes only. Always ensure you have proper authorization before scanning any target. The authors are not responsible for any misuse of this tool.

‎discord_bot.py‎

Lines changed: 0 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -83,7 +83,6 @@ def get_discord_webhook(self) -> Optional[str]:
8383
async def run_autoar_command(self, command: list, scan_id: str, timeout: int = 30) -> Dict[str, Any]:
8484
"""Run AutoAR command and return results."""
8585
try:
86-
print(f"[DEBUG] Running command: {' '.join(command)}")
8786

8887
# Set environment variables
8988
env = os.environ.copy()
@@ -113,11 +112,6 @@ async def run_autoar_command(self, command: list, scan_id: str, timeout: int = 3
113112
'timestamp': datetime.now().isoformat()
114113
}
115114

116-
print(f"[DEBUG] Command exit code: {process.returncode}")
117-
if stdout:
118-
print(f"[DEBUG] Command stdout: {stdout.decode('utf-8')[:200]}")
119-
if stderr:
120-
print(f"[DEBUG] Command stderr: {stderr.decode('utf-8')[:200]}")
121115

122116
return {
123117
'returncode': process.returncode,
@@ -128,7 +122,6 @@ async def run_autoar_command(self, command: list, scan_id: str, timeout: int = 3
128122
}
129123

130124
except Exception as e:
131-
print(f"[DEBUG] Command error: {e}")
132125
return {
133126
'returncode': -1,
134127
'stdout': '',
@@ -947,8 +940,6 @@ async def _send_scan_files(self, scan_id: str, interaction: discord.Interaction)
947940
return
948941

949942
latest_dir = max(target_dirs, key=os.path.getctime)
950-
print(f"Looking for files in: {latest_dir}")
951-
print(f"Directory contents: {[f.name for f in latest_dir.iterdir()]}")
952943

953944
# Send relevant files based on scan type
954945
files_to_send = []

0 commit comments

Comments
 (0)