From 8243bb2eee5fea8056638d8289ffe60d07871c62 Mon Sep 17 00:00:00 2001 From: root-Manas Date: Tue, 6 Jan 2026 11:16:41 +0530 Subject: [PATCH] docs: Add AI context file (.ai/CONTEXT.md) Reference file for AI assistants to understand the project quickly. Contains architecture, CLI flags, tools list, and common tasks. --- .ai/CONTEXT.md | 200 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 200 insertions(+) create mode 100644 .ai/CONTEXT.md diff --git a/.ai/CONTEXT.md b/.ai/CONTEXT.md new file mode 100644 index 0000000..aa42b93 --- /dev/null +++ b/.ai/CONTEXT.md @@ -0,0 +1,200 @@ +# Macaron - AI Context File + +> Read this file at the start of every session to understand the project. + +## What is Macaron? + +Macaron is a **pure reconnaissance platform** for bug bounty hunters. It orchestrates 48+ security tools to gather data about targets. It does NOT do vulnerability scanning - only recon. + +**Version**: 2.4.0 +**Language**: Python 3.9+ +**Platform**: Linux (Kali/Ubuntu/Debian) +**Author**: root-Manas + +## Project Structure + +``` +macaron/ +├── macaron # Main script (single file, ~2400 lines) +├── config/ +│ ├── config.yaml # Main config (discord, proxy, rate limits) +│ └── pipeline.yaml # Tool definitions & scan modes +├── tests/ +│ └── test_cli.py # 14 CLI tests +├── .github/workflows/ +│ └── ci.yml # GitHub Actions CI +├── install.sh # Installation script +├── requirements.txt # Python deps (rich, pyyaml) +├── setup.py +└── README.md +``` + +## Architecture + +### Single-File Design +The entire tool is in one file (`macaron`) for easy installation: +```bash +sudo cp macaron /usr/local/bin/ +``` + +### Key Classes/Components + +| Component | Purpose | +|-----------|---------| +| `ToolRunner` | Executes tools from YAML config | +| `ScanEngine` | Orchestrates scan pipelines | +| `StateManager` | Saves/restores scan state for resume | +| `DiffTracker` | Tracks new assets between scans | +| `ScreenshotGallery` | Generates HTML gallery from screenshots | +| `DiscordNotifier` | Sends Discord webhook notifications | + +### Data Flow + +``` +Target → Subdomain Discovery → DNS Resolution → Port Scan → HTTP Probe → URL Mining → Screenshots → Gallery +``` + +### Config System + +1. **pipeline.yaml**: Defines tools and scan modes + - Tool commands with placeholders: `{target}`, `{input_file}`, `{output_dir}` + - 5 scan modes: wide, narrow, fast, osint, deep + - Each mode has stages with tools + +2. **config.yaml**: Runtime settings + - Discord webhook + - Proxy settings + - Rate limits + +## CLI Flags + +``` +SCANNING: + -s TARGET Scan target(s) + -F FILE From file + --stdin From stdin + -m MODE Mode: wide|narrow|fast|osint|deep + -f Fast mode + -n Narrow mode + --resume Resume interrupted scan + --slow 10 req/s + --rate N Custom rate + --threads N Threads + -q Quiet + +RESULTS: + -S Status + -R Results (use -d) + -G Gallery (use -d) + -E Export JSON + -d DOMAIN Filter domain + -w TYPE subdomains|live|ports|urls|js|diff + -o FILE Output file + +CONFIG: + -C Show config + -P Pipeline path + --webhook URL Set Discord + --test Test webhook + +TOOLS: + -L List tools + -I Install tools (sudo) + -U Update macaron +``` + +## 48 Tools by Category + +| Category | Tools | +|----------|-------| +| Subdomain | subfinder, amass, assetfinder, findomain, github-subdomains | +| Permutation | altdns, dnsgen, shuffledns, puredns | +| DNS | dnsx, massdns, dnsrecon, hakrevdns | +| ASN/IP | asnmap, mapcidr | +| Ports | naabu, masscan, nmap | +| HTTP | httpx, httprobe | +| Fingerprint | whatweb, webanalyze, favfreak | +| URLs | gau, waybackurls, katana, hakrawler, gospider | +| Parameters | paramspider, arjun, x8 | +| API | kiterunner | +| JS | getJS, subjs, linkfinder | +| Content | ffuf, feroxbuster | +| Cloud | cloud_enum, s3scanner | +| Takeover | subjack | +| OSINT | theHarvester, emailfinder, shodan | +| Screenshots | gowitness, eyewitness | + +## 5 Scan Modes + +| Mode | Command | Use Case | +|------|---------|----------| +| wide | `macaron -s target` | Full infrastructure recon | +| fast | `macaron -s target -f` | Quick subdomain + probe | +| narrow | `macaron -s target -n` | Single app, deep crawl | +| osint | `macaron -s target -m osint` | Passive, no contact | +| deep | `macaron -s target -m deep` | Everything + bruteforce | + +## Output Files + +All in `~/.macaron/data//`: +- `subdomains.txt`, `live_hosts.txt`, `ports.txt` +- `urls.txt`, `js_files.txt`, `parameters.txt` +- `technologies.txt`, `takeovers.txt` +- `gowitness/` (screenshots + gallery.html) +- `diff_report.txt`, `summary.json` + +## Testing + +```bash +# Run all tests +pytest tests/ -v + +# Tests must pass before PR merge (CI enforces this) +``` + +## Common Tasks + +### Add a new tool +1. Add to `pipeline.yaml` under `tools:` +2. Add to appropriate scan mode stages +3. Add to `-L` list in `cmd_tools()` +4. Add install command in `cmd_install()` + +### Add a new scan mode +1. Add to `pipeline.yaml` under `pipelines:` +2. Define stages with tools +3. Update help text in `main()` + +### Fix a bug +1. Create branch: `git checkout -b fix/description` +2. Make changes +3. Run tests: `pytest tests/ -v` +4. Commit, push, create PR +5. Wait for CI to pass +6. Merge + +## Important Notes + +1. **Pure Recon Only** - No vulnerability scanning in default pipelines +2. **Linux Only** - Uses Linux tools (apt, go, bash) +3. **Single File** - Keep everything in `macaron` for easy install +4. **YAML-Driven** - Tools defined in pipeline.yaml, not hardcoded +5. **Rich Console** - Uses `force_terminal=True, stderr=True` for CI compatibility + +## Version History + +| Version | Changes | +|---------|---------| +| 2.4.0 | Full 48-tool installer | +| 2.3.0 | 5 scan modes, screenshot gallery, 48 tools | +| 2.2.0 | Diff tracking, resume support, Discord | +| 2.1.0 | YAML pipeline config | +| 2.0.0 | Complete rewrite | + +## Links + +- GitHub: https://github.com/root-Manas/macaron +- Issues: https://github.com/root-Manas/macaron/issues + +--- +*Last updated: 2026-01-06*