Repository Security Scanner

Scan a Git repository for malware, backdoors, and sketchy dependencies before you clone it. Static analysis, OSV.dev vulnerability checks, secret detection, entropy analysis, and Dockerfile linting in a single Python CLI.

The scanner flags:

• Crypto miner patterns
• Backdoor signatures
• Data exfiltration code
• Obfuscation techniques
• Dangerous function calls
• Vulnerable dependencies
• High-entropy (encrypted or obfuscated) files
• Hardcoded secrets and API keys
• Insecure Dockerfile patterns

Why?

Cloning a repo to audit it is already too late. Postinstall scripts, Makefiles, and CI configs run before you ever open the code. This tool scans before git clone completes, so you know what you are pulling in before it touches your machine.

Existing tools split the problem. gitleaks and trufflehog focus on secrets. semgrep and bandit focus on your own code. Neither answers the question you actually have when you find a random repo: is this safe to run?

How it compares

Quick Start

git clone https://github.com/MR-UNKNOWN8014/repo-security-scanner.git
cd repo-security-scanner

./setup.sh          # Linux/macOS
setup.bat           # Windows

python run_scanner.py https://github.com/user/repo.git

Or install straight from PyPI:

pip install repo-security-scanner
repo-scanner https://github.com/user/repo.git

Installation

Requires Python 3.8 or higher.

Automated installer

Linux and macOS:

chmod +x setup.sh
./setup.sh

Windows:

setup.bat

The installer verifies your Python version, installs dependencies, and creates the run script. If Python is not on your PATH, it will point you at 3.8+ from python.org.

Manual install

python -m venv venv

source venv/bin/activate     # Linux/macOS
venv\Scripts\activate        # Windows

pip install -r requirements.txt

As a package

The project ships a pyproject.toml, so you can install it as a CLI instead of running scripts directly:

pip install -e .
repo-scanner https://github.com/user/repo.git

Usage

Basic commands

# Remote repository
python run_scanner.py https://github.com/user/repo.git

# Local path
python run_scanner.py /path/to/local/repo

# Quick scan (size limited, good for CI)
python run_scanner.py https://github.com/user/repo.git --mode quick

# Thorough scan with detailed output
python run_scanner.py https://github.com/user/repo.git --mode thorough --detailed

# Export report to JSON
python run_scanner.py https://github.com/user/repo.git --output report.json

# Query OSV.dev for live dependency vulnerabilities
python run_scanner.py https://github.com/user/repo.git --check-vulns

Arguments

Scan modes

For CI pipelines, --mode quick is usually enough. For a full audit, use --mode thorough.

Ignoring known false positives

Drop a .reposecurityignore in the root of the repo being scanned. One glob pattern per line:

# skip test fixtures with fake credentials
tests/fixtures/*
*.sample.env

Lines starting with # and blank lines are ignored. Patterns match both the path relative to the repo root and the filename.

Detection capabilities

Malicious pattern categories

Language-specific detection

Vulnerable dependencies

Offline (default): checks pinned versions of a curated list against known-bad floors. A package is only flagged if the pinned version is actually below the fixed version. Unpinned or unparseable specs are skipped rather than guessed at.

Online (--check-vulns): queries OSV.dev for every pinned dependency in requirements.txt and package.json, not just the list above. Off by default because it sends dependency names and versions to a third party.

Secret detection

Scans every text file for hardcoded credentials: AWS, GitHub, GitLab, Slack, Google, Stripe, Twilio, and SendGrid keys, private key blocks, JWTs, and generic api_key / secret / token / password assignments. Findings report a file and line number, but the value itself is redacted (first and last few characters only). Known placeholder values such as EXAMPLE, changeme, or <your_key_here> are filtered out so docs and templates do not trip it.

A single confirmed secret pushes that file's risk score into the CRITICAL range on its own.

Dockerfile scanning

Any Dockerfile, Dockerfile.*, or *.dockerfile is additionally checked for:

Risk scoring

Scores run 0 to 100. Higher means more risk.

The score is weighted by category. Malicious patterns and dangerous functions dominate. Entropy, base64, and file size are secondary signals. Vulnerable dependencies and Dockerfile findings add per-package or per-finding penalties. A confirmed secret can single-handedly push a file to CRITICAL.

Full breakdown: docs/SCORING_AND_FORMATS.md.

Report formats

Four formats, plus an all option that prints them in sequence:

• simple: one line with risk score, bar, and level
• multi: four-factor breakdown (code quality, security, obfuscation, malicious)
• categories: risk level, score, and file breakdown by severity
• detailed: everything above, plus file stats and top findings

repo-scanner https://github.com/user/repo.git --format simple
repo-scanner https://github.com/user/repo.git --format detailed

Sample output for each format lives in docs/SCORING_AND_FORMATS.md.

JSON and CSV export are separate from the display format:

repo-scanner https://github.com/user/repo.git --output report.json
repo-scanner https://github.com/user/repo.git --output report.csv

Limitations

• Static analysis only. Obfuscated or packed payloads can evade detection.
• Pattern based detection produces false positives. Always review flagged files.
• Not a replacement for sandboxing or VM isolation when running untrusted code.
• Entropy detection is tuned to be sensitive. High entropy is a signal, not proof.
• Offline dependency checks cover a small curated list. Use --check-vulns for full coverage.

Project structure

repo-security-scanner/
├── setup.sh                     # Linux/macOS installer
├── setup.bat                    # Windows installer
├── requirements.txt             # Python dependencies
├── pyproject.toml               # Packaging
├── README.md
├── LICENSE
├── run_scanner.py               # Entry point
├── main.py                      # CLI entry point
│
├── .github/
│   ├── SECURITY.md               # Vulnerability reporting policy
│   ├── PULL_REQUEST_TEMPLATE.md
│   ├── ISSUE_TEMPLATE/
│   │   ├── bug_report.md
│   │   ├── feature_request.md
│   │   ├── false_positive.md
│   │   └── config.yml
│   └── workflows/
│       ├── tests.yml            # CI: test suite on push/PR
│       └── publish.yml          # Publish to PyPI on GitHub Release
│
├── docs/
│   └── SCORING_AND_FORMATS.md   # Risk scoring and report format docs
│
├── tests/
│   ├── test_entropy_calculator.py
│   ├── test_pattern_matcher.py
│   ├── test_dependency_checker.py
│   ├── test_file_utils.py
│   ├── test_scoring.py
│   ├── test_secret_detector.py
│   └── test_dockerfile_scanner.py
│
└── repo_scanner/
    ├── __init__.py
    ├── config.py
    ├── cli/
    │   └── arguments.py
    ├── scanner/
    │   ├── core.py
    │   ├── file_analyzer.py
    │   ├── pattern_matcher.py
    │   ├── dependency_checker.py
    │   ├── entropy_calculator.py
    │   ├── secret_detector.py
    │   └── dockerfile_scanner.py
    ├── report/
    │   ├── formatter.py
    │   └── exporters.py
    ├── models/
    │   └── scan_result.py
    └── utils/
        ├── file_utils.py
        └── git_utils.py

Troubleshooting

Contributing

Pull requests welcome.

1. Fork the repo
2. Create a branch: git checkout -b feature/my-feature
3. Run the tests: python -m unittest discover -s tests -v
4. Commit: git commit -m 'Add my feature'
5. Push: git push origin feature/my-feature
6. Open a Pull Request

All PRs must pass CI (.github/workflows/tests.yml, Python 3.8 and 3.12) and stay compatible with Python 3.8+.

Reporting issues

When filing a bug, include:

• What you expected
• What actually happened
• Steps to reproduce
• OS and Python version
• Relevant logs or screenshots

License

MIT. See LICENSE.