HackScan

A Python security scanner that verifies what it reports. HackScan finds injection sinks with its own AST engine, then runs a flow-sensitive taint analysis to decide, per finding, whether untrusted input really reaches it. It can also ingest Semgrep, Bandit, CodeQL and Gitleaks results, merge duplicates across tools, and emit one SARIF report.

$ hackscan scan app/
HIGH     confirmed  views.py:10:9  HS-SQLI-001  [100%]
    SQL query is built with string formatting/concatenation.
    | cursor.execute("SELECT * FROM sales WHERE year = " + year)
    > Untrusted request data (`request.GET`) at line 8.
    > Untrusted input reaches the sink.

Why another scanner?

Install

pip install hackscan        # or: uv tool install hackscan / pipx install hackscan

Python 3.10–3.13, any OS. No network access and no LLM needed.

Usage

hackscan scan .                                   # text report
hackscan scan . --format sarif -o hackscan.sarif  # for GitHub code scanning
hackscan scan . --fail-on high                    # exit 1 on open high/critical findings
hackscan scan . --format json --show-suppressed   # everything, machine-readable
hackscan scan . --with bandit,semgrep,gitleaks    # also run these tools if installed
hackscan scan . --import codeql=results.sarif     # merge a report you already have
hackscan rules                                    # list rules

Exit codes: 0 OK, 1 --fail-on threshold reached, 2 usage/config/plugin error or an incomplete scan (a file could not be parsed or read, or an --import report could not be loaded; use --allow-incomplete to accept). A --with tool that is missing or exits with an error is a warning, or exit 2 with --strict-tools. An incomplete scan is never reported as a pass, and SARIF marks it with executionSuccessful: false.

Configuration

.hackscan.yml files are discovered from the filesystem root down to the scanned directory and merged (nearest wins; ignore lists accumulate). CLI options override them.

ignore: [tests/*, "**/migrations/**"]
severity: medium
min-confidence: 40
fail-on: high
with: [bandit]
import:
  codeql: codeql-results.sarif
plugins: security/rules

Suppressing a finding

os.system(cmd)  # hackscan: ignore[HS-CMDI-001]

Suppressed findings stay in SARIF output (as suppressions) so they remain auditable; use --sarif-omit-suppressed when uploading to GitHub, which does not honor them.

Secrets are never echoed: findings of class secret (from any tool) have generic messages and redacted snippets, and values reported by Gitleaks are scrubbed from all output, including warnings.

Rules

Sanitizers recognized: numeric/UUID conversions (all classes), psycopg sql.Identifier /sql.Literal (SQL). shlex.quote is POSIX-only, so quoted commands are kept as low-confidence candidates rather than suppressed.

Custom rules

# security/rules/pickle_rule.py
from hackscan.core.models import Severity
from hackscan.plugins import Match, RulePlugin


class PickleLoads(RulePlugin):
    rule_id = "ACME-PICKLE-001"  # the HS- prefix is reserved
    name = "pickle-loads"
    description = "pickle.loads on untrusted data"
    severity = Severity.HIGH
    cwe = ("CWE-502",)

    def check(self, node, ctx):
        if "pickle.loads" in ctx.call_names(node):
            yield Match(node, "pickle.loads call")

GitHub Actions

- run: pipx install hackscan
- run: hackscan scan . --format sarif --sarif-omit-suppressed -o hackscan.sarif --fail-on high
- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: hackscan.sarif

Limitations

• Taint analysis is intra-procedural: values arriving through function parameters are candidates, not confirmations (inter-procedural analysis is on the roadmap).
• Python only. Imported tools may cover other languages; their findings are passed through.

Development

uv sync --group dev
uv run pytest
uv run ruff check . && uv run ruff format --check .

See PROJECT.md for the design, milestones and decision log.

License

MIT