Raven

README

Raven

Raven is a modern, fast, smart and lightweight reconnaissance tool for redteaming , created by @Nowafen.

English • Persian

[!Note]

Built in Go, it offers a robust and user-friendly experience for discovering subdomains and fuzzing backup files of a target domain, with advanced features to minimize false positives and optimize performance.
Latest version: 0.1.5
Executive environment:‌ Command line interface
Program language: Golang
Number of useful lines: 2661

---

Why Raven?

Raven stands out from the traditional techniques of subdomain enumeration and backup scanning due to its modern design and advanced capabilities. It can help researchers a lot by using fine and precise details. Raven is not a quick-turnaround tool and is built for long-term use, focusing on long-term scanning and target investigation.

---

Installation

[!NOTE]

Ensure you have the following installed:
Go: Version 1.21 or higher
curl: For downloading the default wordlist
git: For cloning the repository
mage: For building the project

1. Build the project

Clone the repository and use mage to check prerequisites and build the binary:

git clone https://github.com/Nowafen/Raven.git
cd Raven
go install github.com/magefile/mage@latest
mage Build
./cmd/raven/raven --version

2. Simple way by installing the binary:

curl -L -o raven https://github.com/Nowafen/Raven/releases/download/v0.1.5/raven
chmod +x raven
./raven --version

Test

./raven -h

help message

./raven -h

Raven v0.1.4 - Subdomain & Backup Scanner
Usage: raven --mode {subdomain|backup} [options]

Modes:
  --mode {subdomain|backup}  Select scan mode (default: subdomain)
  Example: raven -d example.com --mode subdomain

Target Options:
  -d, --domain    Target domain, IP, or CIDR range
  -l, --list      Domain/subdomain list file
  -w, --wordlist  Wordlist for subdomains or backup paths
  Example: raven -d example.com -w wordlist.txt

HTTP Options:
  -H, --header   Custom HTTP headers
  -m, --method   HTTP method (GET, POST, HEAD, TRACE)
  --proxy        Proxy URL
  --resolver     DNS resolver IP or file
  Example: raven -d example.com -H "Cookie:abcd" --resolver 8.8.8.8

Output & Validation:
  -o, --output        Save results to file
  -q, --progress-bar  Show progress bar, delay results
  -v, --validation    Show status codes or file sizes
  --silent            Silent mode (no banner or progress)
  Example: raven -d example.com -q -o results.txt

Filtering:
  -f, --filter-status  Filter status codes
  -c, --match-code     Match status codes
  Example:             raven -d example.com -c 200,301
  Note:  Cannot use --filter-status and --match-code together

Performance:
  -t, --threads     Number of threads (default: 10)
  -r, --rate-limit  Requests per second (default: 100)
  Example: raven -d example.com -t 50 -r 200

Utility:
  --configfile  Manage config (enable|disable|show|reset) [disabled]
  --update      Update tool
  --version     Show version
  -h            This help
  --help        Detailed help
  Example:      raven --configfile show

Move the Binary to a System Path (Optional)

To run raven from anywhere, move the binary to a directory in your PATH (linux):

sudo mv raven /usr/local/bin/

Usage

Full help message

./raven --help

{Raven - Subdomain & Backup Scanner Tool}
Version: 0.1.4

{Introduction}
Raven is a powerful tool for discovering subdomains and finding backup files on a target domain, IP, or IP range. It supports two modes: {subdomain} for enumerating subdomains and {backup} for scanning sensitive backup files (e.g., config.bak, .env). Use the flags below to configure your scan. For issues or contributions, visit the repository.

{Usage}
  raven --mode {subdomain|backup} [options]

{Modes}
  --mode {subdomain|backup}
    Select the scan mode (default: subdomain).
    - {subdomain}: Enumerates subdomains by combining a wordlist with the target domain (e.g., api.example.com).
    - {backup}: Scans for sensitive backup files on the specified target(s).
    Example: raven -d example.com --mode subdomain
    Example: raven --mode backup -d api.example.com -w backup.txt

{Target Options}
  -d, --domain <domain>
    Specify the target domain (e.g., example.com), IP (e.g., 192.168.1.1), or CIDR range (e.g., 192.168.1.0/24). Required for single-target scans.
    Example: raven -d example.com
  -l, --list <path>
    File containing a list of domains/subdomains/IPs (one per line). Required for multi-target scans in backup mode.
    Example: echo -e "api.example.com\nmail.example.com" > targets.txt && raven --mode backup -l targets.txt
  -w, --wordlist <path>
    Path to a wordlist file for subdomains (e.g., api, www) or backup paths (e.g., /backup.json, /.env). Default: /tmp/.raven/subdomains.txt for subdomain mode, /tmp/.raven/backup.txt for backup mode.
    Note: Large wordlists (>100,000 lines) may increase scan time significantly.
    Example: raven -d example.com -w subdomains.txt
    Example: raven --mode backup -d api.example.com -w backup.txt

{HTTP Options}
  -H, --header <header:value>
    Add custom HTTP headers to requests. Can be used multiple times.
    Example: raven -d example.com -H "Cookie: session=abcd" -H "User-Agent: Raven"
  -m, --method <method>
    HTTP method to use (default: GET). Supported: GET, POST, HEAD, TRACE.
    Example: raven -d example.com -m HEAD
  --proxy <url>
    Route requests through a proxy (e.g., http://127.0.0.1:8080). Requires listening on the proxy to capture responses.
    Warning: Responses are only accessible via the proxy; results may be incomplete without proper proxy setup.
    Example: raven -d example.com --proxy http://127.0.0.1:8080
  --resolver <ip or file>
    Custom DNS resolver (IP or file with IPs, e.g., 8.8.8.8 or resolvers.txt). Used in subdomain mode for DNS lookups.
    Example: raven -d example.com --resolver 8.8.8.8

{Output & Validation}
  -o, --output <path>
    Save scan results to a file.
    Example: raven -d example.com -o results.txt
  -q, --progress-bar
    Display a progress bar and delay results until scan completion. Results are shown after scan or saved with -o.
    Example: raven -d example.com -q
  -v, --validation
    Show status codes (subdomain mode) or file sizes (backup mode) in output.
    Example: raven -d example.com -v
  --silent
    Suppress banner and progress output for minimal console output.
    Example: raven -d example.com --silent

{Filtering}
  -f, --filter-status <codes>
    Exclude specific status codes (comma-separated, e.g., 404,403).
    Example: raven -d example.com -f 404,403
  -c, --match-code <codes>
    Include only specific status codes (comma-separated, e.g., 200,301). Overrides default codes (200, 401, 403, 404) in backup mode.
    Example: raven -d example.com -c 200,301
    Note: Cannot use --filter-status and --match-code together.

{Performance}
  -t, --threads <number>
    Number of concurrent threads (default: 10, max: 1000).
    Example: raven -d example.com -t 100
  -r, --rate-limit <number>
    Maximum requests per second (default: 100).
    Example: raven -d example.com -r 500

{Configuration}
  --configfile {enable|disable|show|reset}
    Manage YAML configuration file (/tmp/.raven/filter.yaml). Status: disabled
    - {enable}: Activate YAML config for advanced filtering.
    - {disable}: Deactivate YAML config.
    - {show}: Display current config.
    - {reset}: Reset config to default template.
    Example: raven --configfile show

{Utility}
  --update
    Check and update Raven to the latest version.
    Example: raven --update
  --version
    Display the current version of Raven.
    Example: raven --version
  -h
    Show brief help message.
    Example: raven -h
  --help
    Show this detailed help message.
    Example: raven --help

{Backup Mode Details}
In {backup} mode, Raven scans for sensitive files using a wordlist of paths. The process includes:
  1. {Status Code Filtering}: Responses with status codes 200, 401, 403, or 404 are included by default, unless overridden by --match-code or filtered by --filter-status.
  2. {Content-Type Filtering}: Excludes responses with unwanted Content-Types (e.g., text/html) and includes specific types (e.g., application/json) based on /tmp/.raven/filter_words.json.
  3. {Keyword Checks}: Includes responses with sensitive keywords (e.g., 'password', 'api_key') and excludes those with error-related words (e.g., 'Not Found') from filter_words.json.
  Note: Filter words are downloaded from https://raw.githubusercontent.com/Nowafen/Raven/refs/heads/main/Config/filter_words.json if missing.

  Example: raven --mode backup -d api.example.com -w backup.txt -c 200,403

{Key Examples}
  {Subdomain Discovery}
    raven -d example.com  # Basic subdomain scan
    raven -d example.com -v -q  # With status codes and progress bar
    raven -d example.com -w subdomains.txt -t 200  # Custom wordlist and high concurrency
  {Backup File Scanning}
    raven --mode backup -d api.example.com -w backup.txt -v  # Scan single domain for backup files
    raven --mode backup -l targets.txt -w backup.txt -o results.txt  # Scan multiple targets from a file
    raven --mode backup -d api.example.com -w backup.txt -c 200,403 --proxy http://127.0.0.1:8080  # Use proxy and match specific status codes
  {Configuration}
    raven --configfile show  # View and manage config
    raven --configfile enable
  # Enable YAML config
{Important Notes}
  - Default protocol is {HTTPS} for domains and {HTTP} for IPs if no scheme (http:// or https://) is specified.
  - Ports are preserved if included in the target (e.g., example.com:8080).
  - Large scans (>1M packets) trigger a warning to alert about potential long scan times.
  - Invalid flags display: [*] Invalid or unknown flag. Use -h for help.
  - Currently supports Linux only. Windows support planned for future versions.

{Repository & Support}
  - {Source Code}: https://github.com/Nowafen/Raven
  - {Report Issues}: https://github.com/Nowafen/Raven/issues 
  - For bugs or feature requests, please create an issue on the GitHub repository.

---

Contributing

Contributions are welcome! GitHub repository.