ABScanner - Abbas Bhai Scanner

ABScanner is a focused Python-based sensitive data detection tool designed to recursively scan files and directories for critical security vulnerabilities: username/password pairs and credit card numbers. The scanner uses advanced regex patterns with sophisticated false positive filtering and supports multiple file formats including text files, Microsoft Office documents, PDFs, and various configuration files.

Note:

Avoid scanning code files, while this automatically ignore environments and node_modules, code containing keywords like "password" or "auth" or "username" will be hit. If ommiting code files is not an option, feel free to update the config/patterns.json and check out the src/patterns.py

🔍 Features

• Multi-format Support: Scans text files, .docx, .xlsx, .pptx, .pdf, and many other file formats
• Focused Detection: Specifically targets username/password pairs and credit card numbers
• Advanced False Positive Filtering: Eliminates system constants, hex values, and programming constructs
• Smart Directory Filtering: Automatically skips node_modules, env, .git, and build directories
• Flexible Output: Supports text, JSON, and CSV output formats
• Colorized Console Output: Easy-to-read results with color-coded findings
• Configurable Patterns: Customizable regex patterns via JSON configuration
• Performance Optimized: Handles large directory structures efficiently

🎯 Detection Focus

ABScanner is specifically designed to detect the most critical credential exposures:

• 🔐 Credentials: Username/password pairs in various formats

  • username="value" / password="value" assignments
  • Connection string credentials
  • Configuration file credentials
  • Environment variable patterns

• 💳 Credit Cards: Valid credit card numbers

  • Visa, MasterCard, American Express, Discover
  • Luhn algorithm validation
  • Multiple format support (with/without spaces/dashes)

🚫 Advanced False Positive Filtering

ABScanner includes sophisticated filtering to eliminate common false positives:

• System constants and hex values
• Programming language constructs
• Variable assignments vs. actual credentials
• Test data and placeholder values
• Code comments and documentation

📦 Installation

Option 1: Prebuilt Packages (Recommended)

Windows:

1. Download the Windows package from releases
2. Extract and run install.bat as Administrator
3. Restart command prompt
4. Use abscanner from anywhere

Linux (Ubuntu/Debian):

# Download and install .deb package
sudo dpkg -i abscanner_1.0.0_all.deb

Linux (RedHat/CentOS/Fedora):

# Install .rpm package  
sudo rpm -i abscanner-1.0.0-1.noarch.rpm

Linux (Generic):

# Extract and install
tar -xzf abscanner-linux-generic.tar.gz
cd abscanner-linux
sudo ./install.sh

Option 2: From Source

1. Clone or download the ABScanner project
2. Navigate to the project directory:

   cd ABScanner

3. Install dependencies:

   pip install -r requirements.txt

Option 3: Using pip (Coming Soon)

pip install abscanner

🖥️ Usage

After Installation (Prebuilt Packages)

# Basic scan
abscanner /path/to/scan

# Save results to file  
abscanner /path/to/scan --output results.txt

# JSON output format
abscanner /path/to/scan --output results.json --format json

# Get help
abscanner --help

From Source

Basic Usage

python main.py <directory_path>

Save Results to File

python main.py <directory_path> --output results.txt

JSON Output Format

python main.py <directory_path> --output results.json --format json

CSV Output Format

python main.py <directory_path> --output results.csv --format csv

Disable Colors (for logs/scripts)

python main.py <directory_path> --no-colors

Verbose Output

python main.py <directory_path> --verbose

📊 Example Output

🔍 Starting ABScanner...
📂 Scanning directory: /path/to/scan
⏰ Started at: 2025-08-12 14:22:34
------------------------------------------------------------
Scanning directory: /path/to/scan
------------------------------------------------------------
✅ Scan completed! Found 676 credential findings after filtering.

SUMMARY:
Total findings: 676
Files affected: 10

Findings by category:
  - credentials: 676
  - credit_cards: 0

🎯 FOCUSED RESULTS:
Real credentials found: 1 unique username/password pair
Files with credentials: 7 Python scripts
Risk level: HIGH (Hardcoded credentials detected)

⚙️ Configuration

The regex patterns used for detecting sensitive information can be customized in the config/patterns.json file. The configuration focuses on credentials and credit cards:

{
    "patterns": {
        "credentials": [
            "(?i)(username|user|login)\\s*[:=]\\s*['\"]?([^\\s'\"]+)",
            "(?i)(password|pass|pwd)\\s*[:=]\\s*['\"]?([^\\s'\"]+)"
        ],
        "credit_cards": [
            "\\b(?:4[0-9]{12}(?:[0-9]{3})?|5[1-5][0-9]{14}|3[47][0-9]{13})\\b"
        ]
    }
}

🔧 Additional Tools

ABScanner includes specialized extraction tools:

• extract_real_credentials.py: Ultra-focused credential extraction with advanced filtering
• summary_report.py: Generates clean summary reports of findings
• FINAL_RESULTS.txt: Human-readable summary of scan results

📁 Project Structure

ABScanner/
├── main.py              # Main CLI entry point
├── README.md            # This documentation
├── requirements.txt     # Python dependencies
├── setup.py             # Package setup configuration
├── FINAL_RESULTS.txt    # Example scan results
├── config/
│   └── patterns.json    # Regex pattern definitions
├── src/
│   ├── __init__.py
│   ├── scanner.py       # Core scanning engine
│   ├── patterns.py      # Pattern management & filtering
│   ├── utils.py         # File processing utilities
│   └── reporter.py      # Report generation
├── tests/
│   ├── __init__.py
│   ├── test_scanner.py  # Scanner tests
│   ├── test_patterns.py # Pattern tests
│   └── test_data/       # Test files
└── output/              # Default output directory

🏗️ Building Packages

To create distributable packages:

Windows:

# Install PyInstaller
pip install pyinstaller

# Build Windows executable
build.bat windows

# Or build everything
build.bat all

Linux:

# Build Linux packages (.deb, .rpm, .tar.gz)
make linux

# Or build everything  
make all

See PACKAGING.md for detailed build instructions.

🧪 Testing

Run the test suite:

pytest

📁 Supported File Types

• Text Files: .txt, .py, .js, .html, .css, .json, .xml, .yaml, .yml, .md, .rst, .csv, .log, .cfg, .ini, .conf
• Scripts: .sh, .bat, .ps1, .sql, .php, .jsp, .asp
• Programming: .java, .cpp, .c, .h, .cs, .vb, .rb, .go, .swift, .kt, .scala, .pl, .r, .m
• Documents: .docx, .xlsx, .pptx, .pdf
• Archives: Limited text extraction from certain formats

🔧 Dependencies

• python-docx: For Microsoft Word document processing
• openpyxl: For Excel file processing
• python-pptx: For PowerPoint file processing
• PyPDF2: For PDF text extraction
• colorama: For colored console output
• Standard library: json, os, re, argparse, etc.

⚠️ Important Notes

• False Positive Filtering: ABScanner includes advanced filtering to minimize false positives from system constants, programming constructs, and test data.
• Performance: Large directories are handled efficiently with smart directory filtering (skips node_modules, env, .git, etc.).
• Privacy: Scan results contain actual sensitive information - handle with appropriate security measures.
• Focused Scope: ABScanner specifically targets username/password pairs and credit cards for maximum security impact.
• Permissions: Ensure you have appropriate authorization before scanning any systems or directories.

🤝 Contributing

Contributions are welcome! Areas for improvement:

• Additional file format support
• More sophisticated pattern recognition
• Performance optimizations
• Integration with security tools
• Custom reporting formats

📋 Exit Codes

• 0: No credentials detected
• 1: Credentials found (security issue detected)
• 130: Scan interrupted by user (Ctrl+C)
• Other: Error occurred during scanning

📄 License

This project is licensed under the MIT License. Use responsibly and ensure compliance with your organization's security policies.

---

⚠️ Disclaimer: ABScanner is designed for legitimate security assessment purposes. Users are responsible for ensuring they have proper authorization before scanning any systems or files. The authors are not responsible for any misuse of this tool.