Goodfaith

Goodfaith is a tool for validating testing scope and ensuring compliance with bug bounty program rules and legal testing boundaries. It helps security researchers stay within authorized scope during penetration testing and vulnerability research.

Installation

# Download goodfaith
git clone https://github.com/jobertabma/goodfaith
cd goodfaith

# Install dependencies
pip3 install -r requirements.txt

# Make executable
chmod +x goodfaith.py

# Run
python3 goodfaith.py --help

Basic Commands

# Check version
python3 goodfaith.py --version

# Display help
python3 goodfaith.py --help

# Validate target
python3 goodfaith.py --target example.com --program hackerone

# Check scope
python3 goodfaith.py --scope assets.txt --program bugcrowd

# Load program rules
python3 goodfaith.py --load-rules program.json

# Verify subdomain
python3 goodfaith.py --check-domain api.example.com --program intigriti

Scope Validation

Check Domain Within Scope

# Verify single domain
python3 goodfaith.py --check-domain api.target.com --program hackerone

# Check multiple domains from file
python3 goodfaith.py --check-domains domains.txt --program bugcrowd

# Check IP address
python3 goodfaith.py --check-ip 192.168.1.1 --program intigriti

# Verify subdomain structure
python3 goodfaith.py --check-subdomain staging.api.target.com --program yeswehack

Load Program Rules

# Load HackerOne program
python3 goodfaith.py --load-program target --hackerone

# Load Bugcrowd program
python3 goodfaith.py --load-program target --bugcrowd

# Load custom rules file
python3 goodfaith.py --load-rules program-rules.json

# Check program details
python3 goodfaith.py --show-program target --hackerone

Validate Testing Activities

# Check if activity is allowed
python3 goodfaith.py --activity "SQL injection testing" --program hackerone

# Verify exploitation is permitted
python3 goodfaith.py --activity "data extraction" --scope-file assets.txt

# Check password reset testing
python3 goodfaith.py --activity "password reset bypass" --program bugcrowd

# Validate DDOS testing scope
python3 goodfaith.py --activity "load testing" --program target-program

Scope Analysis

# Parse scope from URL
python3 goodfaith.py --parse-url https://hackerone.com/programs/target

# Extract scope from HTML
python3 goodfaith.py --parse-html program.html --save-scope assets.txt

# Compare scope files
python3 goodfaith.py --compare-scope old-scope.txt new-scope.txt

# Validate asset list
python3 goodfaith.py --validate-scope assets.txt --program bugcrowd

Common Platforms

HackerOne Scope Checking

# Load program
python3 goodfaith.py --program target-name --hackerone

# Check domain
python3 goodfaith.py --domain api.target.com --hackerone

# Get in-scope assets
python3 goodfaith.py --list-assets target-name --hackerone --scope in

# List out-of-scope
python3 goodfaith.py --list-assets target-name --hackerone --scope out

# Check vulnerability type allowed
python3 goodfaith.py --vuln-type "Remote Code Execution" --hackerone

Bugcrowd Scope Integration

# Load Bugcrowd program
python3 goodfaith.py --program target --bugcrowd

# Parse Bugcrowd scope
python3 goodfaith.py --fetch-scope target --bugcrowd --save assets.txt

# Validate target
python3 goodfaith.py --validate target.com --bugcrowd

# Check test types
python3 goodfaith.py --test-types target --bugcrowd

Intigriti Compliance

# Check Intigriti program
python3 goodfaith.py --program target --intigriti

# Get scope info
python3 goodfaith.py --scope-info target --intigriti

# Validate domain
python3 goodfaith.py --validate domain.com --intigriti

Reporting and Documentation

Generate Scope Report

# Create scope documentation
python3 goodfaith.py --report-scope assets.txt --output report.txt

# Generate HTML report
python3 goodfaith.py --report-scope assets.txt --format html --output report.html

# Compare two reports
python3 goodfaith.py --compare report1.txt report2.txt --output diff.txt

# Validate findings against scope
python3 goodfaith.py --validate-findings findings.txt --scope scope.txt

Audit Trail

# Log all testing activities
python3 goodfaith.py --log-activity "Tested domain" api.target.com

# View activity log
python3 goodfaith.py --show-log

# Export audit trail
python3 goodfaith.py --export-log audit.csv --format csv

# Timestamp findings
python3 goodfaith.py --timestamp-finding vuln_description --save findings.log

Scope Definition Examples

Creating a Scope File

# Format: domains or IPs, one per line with comment after #
cat > scope.txt << 'EOF'
# In Scope
*.target.com
api.target.com
admin.target.com # Administrative interface
192.168.1.0/24 # Internal network

# Out of Scope (for reference)
# legacy.target.com
# sandbox.target.com
EOF

# Validate scope file
python3 goodfaith.py --validate-scope scope.txt

Subdomain Wildcard Rules

# Test wildcard matching
python3 goodfaith.py --check-domain test.api.target.com --wildcard "*.api.target.com"

# Multiple wildcard patterns
python3 goodfaith.py --load-rules patterns.json --check-domain internal.target.co.uk

# Domain expansion
python3 goodfaith.py --expand-wildcards scope.txt --output expanded-scope.txt

Batch Operations

Process Multiple Domains

# Check multiple domains in parallel
python3 goodfaith.py --check-domains domains.txt --program bugcrowd --parallel

# Test against scope file
python3 goodfaith.py --test-list domains.txt --scope assets.txt --verbose

# Generate report for all domains
python3 goodfaith.py --batch domains.txt --report output/ --program hackerone

Cross-Platform Scope Comparison

# Compare HackerOne and Bugcrowd scopes for same target
python3 goodfaith.py --compare-platforms target --hackerone --bugcrowd

# Export scope differences
python3 goodfaith.py --diff-platforms hackerone-scope.txt bugcrowd-scope.txt

Automation with Goodfaith

Bash Integration

#!/bin/bash
# Validate all discovered targets before testing

TARGETS_FILE="discovered_targets.txt"
PROGRAM="target-name"
SCOPE_FILE="verified-scope.txt"

# Clear previous verified scope
> "$SCOPE_FILE"

# Validate each target
while IFS= read -r target; do
    if python3 goodfaith.py --check-domain "$target" --program hackerone; then
        echo "$target" >> "$SCOPE_FILE"
        echo "[+] In scope: $target"
    else
        echo "[-] Out of scope: $target"
    fi
done < "$TARGETS_FILE"

echo "[*] Verified scope saved to $SCOPE_FILE"

Python Integration

#!/usr/bin/env python3
"""
Goodfaith scope validator for automated workflows
"""

import subprocess
import json
from typing import List, Dict

class GoodfaithValidator:
    def __init__(self, program: str, platform: str = "hackerone"):
        self.program = program
        self.platform = platform

    def check_domain(self, domain: str) -> bool:
        """Check if domain is in scope"""
        cmd = [
            'python3', 'goodfaith.py',
            '--check-domain', domain,
            '--program', self.program,
            f'--{self.platform}'
        ]

        try:
            result = subprocess.run(cmd, capture_output=True, timeout=10)
            return result.returncode == 0
        except Exception as e:
            print(f"Error checking {domain}: {e}")
            return False

    def validate_targets(self, targets: List[str]) -> Dict[str, bool]:
        """Validate multiple targets"""
        results = {}
        for target in targets:
            results[target] = self.check_domain(target)
        return results

    def get_in_scope(self, targets: List[str]) -> List[str]:
        """Return only in-scope targets"""
        results = self.validate_targets(targets)
        return [t for t, status in results.items() if status]

# Usage
validator = GoodfaithValidator("target-program", "hackerone")
targets = ["api.target.com", "admin.target.com", "staging.target.com"]
in_scope = validator.get_in_scope(targets)

print(f"In-scope targets: {in_scope}")

Rules File Format

Program Rules JSON

{
  "program_name": "Target Program",
  "platform": "hackerone",
  "in_scope": [
    "*.target.com",
    "api.target.com",
    "admin.target.com",
    "192.168.1.0/24"
  ],
  "out_of_scope": [
    "legacy.target.com",
    "staging.target.com",
    "test.target.com"
  ],
  "excluded_vulns": [
    "Email enumeration",
    "Open redirect (low impact)",
    "Self-XSS"
  ],
  "allowed_activities": [
    "Vulnerability scanning",
    "Penetration testing",
    "Social engineering",
    "Code review"
  ],
  "restricted_activities": [
    "Denial of Service",
    "Network packet interception",
    "Physical security testing"
  ],
  "constraints": {
    "no_user_data_exfiltration": true,
    "no_production_impact": true,
    "report_timeline_days": 90
  }
}

Load Custom Rules

# Create rules file for program
python3 goodfaith.py --create-rules program.json

# Load and validate rules
python3 goodfaith.py --load-rules program.json --validate

# Apply rules to testing
python3 goodfaith.py --apply-rules program.json --check-domain api.target.com

Pre-Testing Checklist

Before Starting Engagement

# 1. Download scope from platform
python3 goodfaith.py --fetch-scope target-program --hackerone --save scope.txt

# 2. Verify scope file format
python3 goodfaith.py --validate-scope scope.txt

# 3. Expand wildcard domains
python3 goodfaith.py --expand-wildcards scope.txt --output expanded.txt

# 4. Generate testing documentation
python3 goodfaith.py --report-scope scope.txt --format markdown --output SCOPE.md

# 5. Save copy with timestamp
cp scope.txt scope.$(date +%Y%m%d_%H%M%S).txt

# 6. Verify all constraints understood
python3 goodfaith.py --show-constraints target-program --hackerone

During Engagement

# Before each test, verify target
python3 goodfaith.py --check-domain target-subdomain.com --hackerone

# Log all testing activity
python3 goodfaith.py --log-activity "Testing subdomain" target-subdomain.com

# Verify vulnerability type is reportable
python3 goodfaith.py --check-vuln "Remote Code Execution" --program target

# Export audit trail at end of day
python3 goodfaith.py --export-log daily-audit.csv --date today

Legal Considerations

Stay Within Scope

• Only test systems explicitly listed in scope
• Verify scope with program before testing
• Save scope documentation with timestamp
• Document any out-of-scope discoveries
• Report scope confusion to program immediately
• Never assume authorization extends beyond written scope

Responsible Disclosure

# Verify reporting timeline
python3 goodfaith.py --get-timeline target-program --hackerone

# Check if finding is reportable
python3 goodfaith.py --check-reportable "Information disclosure" --program target

# Track submission deadlines
python3 goodfaith.py --add-deadline "2024-04-30" --finding "SQL injection"

Documentation Best Practices

• Log all testing activities with timestamps
• Keep separate scope documentation
• Document any authorization changes
• Save platform screenshots of scope
• Maintain copies of all correspondence
• Create audit trail for legal protection

Comparison with Alternatives

Tool	Purpose	Focus
Goodfaith	Scope validation	Bug bounty compliance
Burp Suite	Web testing	Vulnerability discovery
Nmap	Network scanning	Infrastructure mapping
Metasploit	Exploitation	PoC development

References

• Goodfaith GitHub
• HackerOne Scope Guidelines
• Bugcrowd Scope Documentation
• Responsible Disclosure Guidelines

---

Last updated: 2026-03-30