Secure Sandbox Scanner

A local-first CLI tool for scanning MP3, MP4, and GitHub repo folders for security risks.
Performs static analysis, classifies files, generates markdown reports, and supports explicit quarantine.

Features

• Static and metadata analysis (no execution)
• YARA rule scanning (customizable, local-only)
• Offline antivirus scan (ClamAV integration, optional)
• Archive unpacking and recursive scan (ZIP, TAR, RAR)
• SBOM (Software Bill of Materials) generation for repos
• Website scanner: scan any HTTP/HTTPS URL for security headers and basic risks
• MP3/MP4/media checks
• GitHub repo static inspection
• Clear verdicts: SAFE, CAUTION, SUSPICIOUS, UNSAFE, UNKNOWN
• Markdown reporting
• Explicit quarantine workflow
• Logging and audit trail

Setup

1. Install Python 3.9+ (Recommended: 3.10 or 3.11)

2. Install system dependencies

macOS

• Install Homebrew if not present: https://brew.sh
• Then run:

  brew install libmagic

Ubuntu/Debian Linux

• Run:

  sudo apt-get update
  sudo apt-get install python3 python3-pip libmagic1 python3-magic

Windows

• Install Python from https://www.python.org/downloads/
• Download and install the GnuWin32 file package or use the python-magic-bin wheel.
• If you see errors about libmagic, follow the python-magic Windows instructions: https://github.com/ahupp/python-magic#windows

3. Install Python dependencies

pip install -r requirements.txt

4. Adjust config/config.yaml if needed

5. Place files in input/mp3/, input/mp4/, or input/github_repos/

6. Run the CLI

python cli.py

Usage

1. Place files in the appropriate intake folder (input/mp3/, input/mp4/, or input/github_repos/).
2. To scan a website, select the "Scan a website (URL)" option and enter the HTTP/HTTPS address when prompted.
3. Run the CLI:

   python cli.py

4. Select a scan option from the menu (e.g., Scan MP4 folder, Scan all folders, Scan a website).
5. Wait for the scan to complete. The CLI will display the path to the generated markdown report.
6. Open the report in reports/ to review findings, recommendations, and SBOMs.
7. If flagged files are found, you will be prompted to move them to quarantine (explicit, never automatic).
8. You can view previous reports or quarantine flagged files at any time from the menu.

Security

• No files are executed or opened.
• Quarantine is explicit and logged.
• "SAFE" means no obvious red flags, not a guarantee.

Limitations

• Heuristic/static analysis only.
• ClamAV and YARA are optional but recommended for best results.
• False negatives/positives possible.

Advanced Features

• YARA rules: Place your custom rules in yara_rules/ (see sample provided).
• ClamAV: Install and run the ClamAV daemon (clamd) for AV scanning. See below for OS-specific install tips.
• Archive scanning: ZIP, TAR, and RAR files are unpacked and scanned recursively.
• SBOM: Dependency lists for repos are included in reports.

ClamAV Installation

macOS

brew install clamav
brew services start clamav

Ubuntu/Debian Linux

sudo apt-get install clamav clamav-daemon
sudo systemctl start clamav-daemon

Windows

• Download from https://www.clamav.net/downloads
• Start the clamd service (see ClamAV docs)

Future

• Dependency reputation checks
• More archive formats
• User-defined policy modes