CyberBro CLI - IOC Search Tool

A command-line interface for searching Indicators of Compromise (IOCs) using the CyberBro API.

Features

• Search IOCs (IPs, domains, URLs, hashes) across multiple threat intelligence sources
• Enable/disable specific analysis modules
• Configurable via config.ini
• Built with Python uv for fast dependency management
• Bash shell installer included
• JSON formatted results

Installation

Prerequisites

• Python 3.9 or higher
• uv package manager
• Bash shell (for the installer script)

Install uv

curl -LsSf https://astral.sh/uv/install.sh | sh

Install CyberBro CLI

# Clone or download the repository
cd /path/to/cyberbrocli

# Run the installer
./install.sh

The installer will:

1. Create ~/.local/bin directory (if needed)
2. Create ~/.config/cyberbrocli directory
3. Copy config.ini to the config directory
4. Install Python dependencies using uv
5. Create a wrapper script cyberbrocli in ~/.local/bin

Add to PATH (if needed)

If ~/.local/bin is not in your PATH, add this to your ~/.bashrc or ~/.bash_profile:

export PATH="$HOME/.local/bin:$PATH"

Then reload your shell configuration:

source ~/.bashrc

Configuration

Edit the configuration file at ~/.config/cyberbrocli/config.ini:

[cyberbro]
# CyberBro API base URL
url = http://localhost:5000/api/

# Maximum timeout for analysis completion (in seconds)
timeout = 300

# Disable SSL certificate verification (use for self-signed certificates or testing)
# WARNING: This is insecure and should only be used in trusted environments
insecure_tls = false

# Proxy configuration (optional)
# Supports HTTP, HTTPS, SOCKS5 proxies
# Examples:
#   http://proxy.example.com:8080
#   socks5://localhost:1080
#   socks5h://proxy.example.com:1080 (DNS resolution through proxy)
proxy =

# HTTP Basic Authentication (optional)
auth_user =
auth_pass =

# Custom User-Agent header (optional)
user_agent = "CyberBro-CLI/1.0"

# Enable colored output (can be disabled with --no-colors)
colors = true

# Enable verbose/debug output (can be enabled with -v or --verbose)
verbose = false

[modules]
# Enable or disable specific modules
abuseipdb = true
virustotal = true
shodan = true
# ... etc

Configuration Options

• url: Base URL of your CyberBro API instance
• timeout: Maximum time (in seconds) to wait for analysis completion
• insecure_tls: Set to true to disable SSL certificate verification (useful for self-signed certificates)
  • WARNING: Only use this in trusted environments as it makes connections vulnerable to MITM attacks
• proxy: Proxy server URL (optional). Supports:
  • HTTP/HTTPS proxies: http://proxy.example.com:8080
  • SOCKS5 proxies: socks5://localhost:1080
  • SOCKS5 with DNS: socks5h://proxy.example.com:1080 (DNS resolution through proxy)
  • Note: For SOCKS proxy support, install requests[socks] or pysocks
• auth_user / auth_pass: HTTP Basic Authentication credentials (optional)
• user_agent: Custom User-Agent header (optional, defaults to CyberBro-CLI/1.0)
• colors: Enable/disable colored terminal output (default: true)
• verbose: Enable verbose/debug output (default: false)
• modules: Enable (true) or disable (false) individual analysis modules

Usage

Basic Usage

# Search a single IOC
cyberbrocli 1.1.1.1
cyberbrocli example.com
cyberbrocli 929c311d58965ae456d96ca118fb7fcabf98699e02d30e0913ddf08a06e8d0c4

# Search multiple IOCs
cyberbrocli test.com example.com 1.1.1.1

# Search IOCs from a file (one per line)
cyberbrocli --file iocs.txt
cyberbrocli -f iocs.txt

Output Formats

ASCII Table Output (Default)

By default, results are displayed as formatted ASCII tables:

• One table per module per IOC
• Colored output with syntax highlighting
• Clean, readable format without emojis
• Automatically truncates long values

cyberbrocli test.com

JSON Output

Use --json flag for JSON format:

# Display as JSON
cyberbrocli example.com --json

# Save to JSON file
cyberbrocli example.com --output results.json

Saves the full API response as a JSON file, perfect for:

• Further processing with tools like jq
• Integration with other scripts
• Archival purposes

CSV Export

cyberbrocli example.com --output results.csv

Exports results as a flattened CSV file with:

• All nested fields flattened with dot notation (e.g., virustotal.detection_ratio)
• Arrays converted to JSON strings
• Suitable for spreadsheet applications or data analysis tools

Display Options

# Disable colored output (for piping or logging)
cyberbrocli 1.1.1.1 --no-colors

# Output as JSON instead of ASCII tables
cyberbrocli example.com --json

# Enable verbose/debug output
cyberbrocli example.com -v
cyberbrocli example.com --verbose

Advanced Options

# Exclude specific modules
cyberbrocli 1.1.1.1 --exclude virustotal shodan

# Override API URL from config
cyberbrocli example.com --url http://cyberbro.example.com/api/

# Force fresh analysis (ignore cache)
cyberbrocli malware.exe --no-cache

# Use custom config file
cyberbrocli 1.1.1.1 --config /path/to/custom/config.ini

# Set custom timeout
cyberbrocli example.com --timeout 600

# Use HTTP proxy
cyberbrocli example.com --proxy http://proxy.company.com:8080

# Use SOCKS5 proxy
cyberbrocli example.com --proxy socks5://localhost:1080

# Use HTTP Basic Authentication
cyberbrocli example.com --auth-user admin --auth-pass secret123

# Custom User-Agent
cyberbrocli example.com --user-agent "MyCustomBot/1.0"

# Combine multiple options
cyberbrocli example.com --proxy socks5://localhost:1080 --auth-user admin --auth-pass secret --user-agent "Scanner/2.0"

Help

cyberbrocli --help

Testing

Test the installation with the test endpoint:

# Test with the demo API (as mentioned in your requirements)
cyberbrocli test.com --url http://localhost:5000/api/

Optional Dependencies

SOCKS Proxy Support

To use SOCKS proxies (socks5:// or socks5h://), you need to install the pysocks package:

# Install pysocks for SOCKS proxy support
uv add pysocks

# Or using pip in the virtual environment
uv run pip install pysocks

Once installed, you can use SOCKS proxies:

# SOCKS5 proxy
cyberbrocli example.com --proxy socks5://localhost:1080

# SOCKS5 with DNS resolution through proxy
cyberbrocli example.com --proxy socks5h://proxy.example.com:1080

Development

Project Structure

cyberbrocli/
├── cyberbrocli.py      # Main Python script
├── config.ini          # Default configuration
├── install.sh          # Bash shell installer
├── README.md           # This file
├── pyproject.toml      # uv project configuration
└── uv.lock             # Locked dependencies

Running without installation

# Activate virtual environment and run
uv run python3 cyberbrocli.py <IOC>

Adding dependencies

uv add <package-name>

How It Works

1. Submit Analysis: The tool submits your IOC to the CyberBro API with selected modules
2. Poll for Completion: It polls the API every 2 seconds to check if analysis is complete
3. Retrieve Results: Once complete, it fetches and displays the results in JSON format

The CyberBro API workflow:

• POST /api/analyze - Submit IOC for analysis (returns analysis_id)
• GET /api/is_analysis_complete/{analysis_id} - Check status
• GET /api/results/{analysis_id} - Get results

Examples

Example 1: Full scan of an IP

cyberbrocli 8.8.8.8

Example 2: Quick scan without resource-intensive modules

cyberbrocli malware.com --exclude virustotal shodan urlscan

Example 3: Using a different CyberBro instance

cyberbrocli 1.1.1.1 --url http://cyberbro.internal.company.com/api/

Example 4: Fresh analysis without cache

cyberbrocli suspicious-domain.com --no-cache

Troubleshooting

Command not found

Make sure ~/.local/bin is in your PATH:

echo $PATH | grep ".local/bin"

Connection errors

• Verify the CyberBro API URL in your config.ini
• Check that CyberBro is running and accessible
• Test with curl: curl http://localhost:5000/api/

Timeout issues

• Increase the timeout in config.ini or use --timeout
• Some modules may take longer to complete
• Consider excluding slow modules for faster results

License

MIT License

Related Links

• CyberBro Documentation
• CyberBro GitHub
• uv Package Manager

Contributing

Feel free to submit issues, feature requests, or pull requests!