Conversation
- Removed all fluff and emojis - Complete command reference with all flags - Every usage example with actual commands - All 5 scan modes explained with tool chains - All 48 tools listed by category - Output files documented - Configuration files explained - Common workflows section - Clean, scannable format
There was a problem hiding this comment.
Pull request overview
This PR completely rewrites the README from a detailed, feature-rich documentation (521 lines) to a concise, command-focused usage guide (374 lines). The rewrite emphasizes practical examples and quick reference over comprehensive explanations.
Key Changes:
- Restructured from feature-oriented to command-oriented documentation
- Removed detailed stage-by-stage breakdowns for each scan mode
- Condensed installation and configuration sections
- Added more practical usage examples and workflow patterns
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
|
|
||
| | Category | Tools | | ||
| |----------|-------| | ||
| | Subdomain | subfinder, amass, assetfinder, findomain, github-subdomains | |
There was a problem hiding this comment.
The Tools section lists "github-subdomains" (line 262) under Subdomain tools, but this tool is not mentioned in any of the scan mode descriptions (lines 228-256) or in the tool chains shown for each mode. Consider verifying that this tool is actually integrated and used, or clarify in which mode(s) it runs.
| | OSINT | theHarvester, emailfinder, shodan | | ||
| | Screenshots | gowitness, eyewitness | | ||
| | Utils | proxychains4, jq, curl | | ||
|
|
There was a problem hiding this comment.
Several tools listed in the Tools section (lines 258-278) are not mentioned in any of the scan mode tool chains. For example, "masscan", "nmap", "httprobe", "webanalyze", "x8", "emailfinder", and "eyewitness" are listed but don't appear in the mode descriptions (lines 232, 238, 244, 250, 256). Consider either adding these tools to the appropriate mode descriptions or clarifying in which contexts they are used.
| Note: The table above lists all tools bundled with Macaron, grouped by capability. Not every tool is invoked in every scan mode; some (for example `masscan`, `nmap`, `httprobe`, `webanalyze`, `x8`, `emailfinder`, `eyewitness`, and the utilities `proxychains4`, `jq`, `curl`) are used only in specific modes or for optional/advanced/manual workflows rather than in the default automated chains. |
| ```bash | ||
| macaron -s example.com -f | ||
| ``` | ||
| Runs: subfinder, crtsh → httpx → gau → gowitness |
There was a problem hiding this comment.
The Fast Mode description (line 238) shows the tool chain as "subfinder, crtsh → httpx → gau → gowitness", but the old README indicated that Fast mode also includes quick subdomain enumeration. The arrow notation suggests a sequential pipeline, but "crtsh" is typically a data source used by tools like subfinder rather than a standalone tool in the chain. Consider clarifying whether "crtsh" refers to a separate tool or if it's part of subfinder's data sources.
| Runs: subfinder, crtsh → httpx → gau → gowitness | |
| Runs: subfinder (using crt.sh as a data source) → httpx → gau → gowitness |
| js_files.txt # JavaScript files | ||
| parameters.txt # URL parameters | ||
| technologies.txt # Tech fingerprints | ||
| takeovers.txt # Subdomain takeover candidates |
There was a problem hiding this comment.
The Output Files section (line 292) mentions "takeovers.txt" for subdomain takeover candidates. However, in the Tools section (line 275), only "subjack" is listed under the Takeover category, while the old README's Deep Mode description mentioned both "subjack" and "nuclei" for takeover detection. Consider clarifying if nuclei is still used for this purpose or if only subjack is responsible for generating takeovers.txt.
| macaron -s target.com # Initial scan | ||
| # ... wait some time ... | ||
| macaron -s target.com # Rescan | ||
| macaron -R -d target.com -w diff # See what's new |
There was a problem hiding this comment.
The "Common Workflows" section mentions using "-w diff" to see new assets (line 341), but the "diff" filter is not explained until it appears in the Viewing Results section (line 148). Additionally, the old README had a detailed "Diff Tracking" section explaining this feature with examples of the output format, which has been completely removed. Consider adding a brief explanation of what the diff tracking feature does and how to interpret its output.
| ``` | ||
|
|
||
| **A powerful CLI-based security reconnaissance platform for bug bounty hunters** | ||
| **Security reconnaissance platform for bug bounty hunters. 48 tools. 5 scan modes. Pure recon.** |
There was a problem hiding this comment.
The tagline mentions "48 tools" but the Tools section (line 258) header also says "48" without providing an explicit count. However, when counting the tools listed in the table (lines 262-278), there appear to be fewer than 48 distinct tools. Consider verifying that all 48 tools are accurately represented in the documentation or updating the count to match the actual number of tools listed.
|
|
||
| # Install recon tools (optional - run as needed) | ||
| sudo ./install.sh | ||
| # Install recon tools |
There was a problem hiding this comment.
The installation instructions suggest using "sudo macaron -I" but line 20 shows "chmod +x macaron" and line 21 shows "sudo cp macaron /usr/local/bin/" which would make the macaron command available system-wide. However, the -I flag for installation is not explained until the TOOLS section below. Consider adding a note that the -I command is for installing reconnaissance tools (not macaron itself) to avoid confusion.
| # Install recon tools | |
| # Install optional reconnaissance tools used by macaron (not macaron itself) |
| -G, --gallery Generate screenshot gallery (use with -d) | ||
| -E, --export Export results to JSON | ||
| -d, --domain DOMAIN Filter by domain | ||
| -w, --what TYPE Filter: all|subdomains|live|ports|urls|js|vulns|diff |
There was a problem hiding this comment.
The flag description says "Filter: all|subdomains|live|ports|urls|js|vulns|diff" but in the "Viewing Results" examples section (line 148), the example shows using "-w diff" and line 143 shows using "-w subdomains". However, the old README mentioned "vulns" (line 147 in old version) but this is replaced with "diff" in the new version (line 148). Consider verifying that "vulns" is still a valid filter option or if it should be removed from the flag description on line 52.
| -w, --what TYPE Filter: all|subdomains|live|ports|urls|js|vulns|diff | |
| -w, --what TYPE Filter: all|subdomains|live|ports|urls|js|diff |
| ```bash | ||
| macaron -s example.com -m deep | ||
| ``` | ||
| Runs: All 18 stages including bruteforce, permutation, full port scan, API discovery, cloud enumeration |
There was a problem hiding this comment.
The Deep Mode description on line 256 mentions "All 18 stages" but doesn't clarify what these 18 stages are. The old README provided detailed stage breakdowns for each mode (which have been removed). Consider either listing what the 18 stages are or providing a reference to where users can find this information (e.g., in pipeline.yaml or documentation).
| Runs: All 18 stages including bruteforce, permutation, full port scan, API discovery, cloud enumeration | |
| Runs: all 18 stages defined in the pipeline configuration (see `pipeline.yaml` / documentation), including bruteforce, permutation, full port scan, API discovery, and cloud enumeration |
| technologies.txt # Tech fingerprints | ||
| takeovers.txt # Subdomain takeover candidates | ||
| summary.json # Scan summary | ||
| diff_report.txt # New assets since last scan |
There was a problem hiding this comment.
The "Output Files" section shows "diff_report.txt" (line 294) with the comment "New assets since last scan", but the old README indicated that diff tracking creates both ".scan_history.json" and "diff_report.txt". The new documentation doesn't mention ".scan_history.json" or explain how diff tracking works. Consider adding this file to the list or clarifying if the feature has changed.
Comprehensive usage guide with all flags and examples.