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

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

Installation

Requires Python 3.8 or higher.

From PyPI

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

From source

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

python -m venv venv
source venv/bin/activate     # Linux/macOS
venv\Scripts\activate        # Windows

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

pip install -e . reads pyproject.toml, which declares requires-python = ">=3.8", so pip refuses to install on an older interpreter. Running python main.py <url> also works from a source checkout without installing.

Usage

Basic commands

# Remote repository
repo-scanner https://github.com/user/repo.git

# Local path
repo-scanner /path/to/local/repo

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

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

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

# Several formats from one scan
repo-scanner https://github.com/user/repo.git -o report.json -o results.sarif

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

Arguments

Exit codes

A threshold breach and a tool failure are deliberately different codes, so CI can tell a risky repository from a broken scanner and never fail open.

# fail the build only on a critical score
repo-scanner https://github.com/user/repo.git -A -F critical

# report everything, never fail the build
repo-scanner https://github.com/user/repo.git -A -F none

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.

GitHub Action

Scan in CI, either your own checkout or a third party repository you are about to trust:

- uses: actions/checkout@v4
- uses: MR-UNKNOWN8014/repo-security-scanner@v1
  with:
    mode: quick
    fail-on: high

The job fails when the score reaches fail-on, and fails separately when the scan itself could not complete, so a broken scan never reads as a pass. Outputs include risk-score, risk-level, findings-count and threshold-exceeded, and SARIF can be uploaded to GitHub Code Scanning.

Inputs, outputs, exit behavior and Code Scanning setup: docs/GITHUB_ACTION.md.

Detection capabilities

Full pattern lists, package lists and per-check behavior: docs/DETECTION_CAPABILITIES.md.

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.

Best practice notes such as long lines are reported as cautions, in their own section, and never affect the score. Every finding and caution reports the file it came from, and a line number wherever one applies.

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
repo-scanner https://github.com/user/repo.git --output results.sarif

SARIF 2.1.0 is rendered natively by GitHub Code Scanning, so scan results show up in the Security tab. See docs/SCORING_AND_FORMATS.md.

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/
├── 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
│
├── action.yml                    # GitHub Action definition
│
├── docs/
│   ├── SCORING_AND_FORMATS.md    # Risk scoring and report formats
│   ├── DETECTION_CAPABILITIES.md # Full detection reference
│   └── GITHUB_ACTION.md          # GitHub Action reference
│
├── tests/
│   ├── test_entropy_calculator.py
│   ├── test_pattern_matcher.py
│   ├── test_dependency_checker.py
│   ├── test_file_utils.py
│   ├── test_formatter.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.