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 (--llm is opt-in).

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 scan . --show-fixes                      # include fix suggestions as diffs
hackscan scan . --llm --model qwen2.5-coder:7b    # triage candidates with local Ollama
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
llm: false
llm-model: qwen2.5-coder:7b

LLM triage

--llm sends each remaining candidate (never confirmed or suppressed findings) with its surrounding function to a local Ollama model and asks for a verdict:

• true positive: the finding becomes confirmed (+15 confidence); a suggested fix is kept only if the patched file parses and a re-scan shows the finding gone and nothing new.
• false positive: only accepted if the model cites a line that HackScan verifies runs on every path and makes the value safe: an allow-list guard (if x not in {...}: return, if not x.isdigit(): raise, or if not x.isdecimal(): raise), a constant, or a class-appropriate sanitizer. isnumeric(), isalnum(), isalpha(), and isidentifier() do not qualify. Otherwise the reasoning is attached as a note and the finding stays open.
• Code is fenced with a random per-request token and treated as untrusted data; replies must match a JSON schema; secret-looking values are redacted; answers are cached.

Use a non-reasoning instruct or coder model. Measured on a CPU-only laptop (~30 s per finding): qwen3:4b-instruct-2507 judged a real injection, a bypassable length check and an allow-list guard correctly; qwen2.5-coder:3b never suppressed but also missed the allow-list guard (larger models do better). Reasoning models such as deepseek-r1 often spend their whole output budget thinking, which HackScan reports as "no answer" and leaves the finding open. In the same test both small models obeyed a comment in the scanned code telling them to answer "false positive"; the deterministic evidence check rejected it and the finding stayed open. That check, not the model, decides suppression.

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.
• Fix suggestions are deliberately conservative: many vulnerable lines get none. Command fixes (argument lists) are only offered for programs whose arguments are inert data (cat, ls, grep, head, ...): many others run operands or options as commands (sh -c, npx PKG, git -c alias=!cmd, tar --to-command). They are also not offered when a value directly follows a flag; put -- before operands to get one. A value starting with - can still be read as an option, so review command fixes. No fix is offered for a call that contains a secret, or for SQL containing comments.
• SQL fixes are not offered for unquoted values inside parentheses, double-quoted identifiers, or SQL text containing backslashes, $, backticks or brackets; redaction of values that coincide with identifiers or tool metadata is best-effort.
• String and bytes literals assigned to secret-looking names (api_key, password, token, ...) are masked in snippets, the LLM context and fix diffs. Their values are also removed from imported messages and evidence before output or LLM triage when the value is secret-like (at least eight characters with a digit or symbol, or at least sixteen characters). Known secrets in proposed fixes cause the fix to be omitted. Imported findings for files that cannot be parsed have no source snippet.

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