hackscan 0.1.0__py3-none-any.whl

hackscan/taint/sanitizers.py

@@ -0,0 +1,37 @@
+"""Sanitizers: calls whose result is safe for some (or all) injection classes."""
+
+from __future__ import annotations
+
+from hackscan.core.taxonomy import CMDI, SQLI, TAINT_CLASSES
+
+ALL = TAINT_CLASSES
+
+# Fully-qualified call name -> vuln classes the result is safe for.
+SANITIZERS: dict[str, frozenset[str]] = {
+    # Numeric / boolean / identifier conversions cannot carry injection payloads.
+    "int": ALL,
+    "float": ALL,
+    "bool": ALL,
+    "abs": ALL,
+    "len": ALL,
+    "round": ALL,
+    "builtins.int": ALL,
+    "builtins.float": ALL,
+    "uuid.UUID": ALL,
+    "decimal.Decimal": ALL,
+    # Shell quoting. Context-sensitive: see QUOTING_SANITIZERS.
+    "shlex.quote": frozenset({CMDI}),
+    "shlex.join": frozenset({CMDI}),
+    "pipes.quote": frozenset({CMDI}),
+    # SQL identifier/literal quoting helpers.
+    "psycopg2.sql.Identifier": frozenset({SQLI}),
+    "psycopg2.sql.Literal": frozenset({SQLI}),
+    "psycopg.sql.Identifier": frozenset({SQLI}),
+    "psycopg.sql.Literal": frozenset({SQLI}),
+}
+
+# Sanitizers whose safety depends on where the result is placed: a shell-quoted value
+# embedded inside another quote context (`'echo "' + shlex.quote(x) + '"'`) is unsafe.
+# Note: `ast.literal_eval` is deliberately absent: it can return a string, which is
+# still dangerous when passed on to eval/exec.
+QUOTING_SANITIZERS = frozenset({"shlex.quote", "shlex.join", "pipes.quote"})

hackscan/taint/sources.py

@@ -0,0 +1,99 @@
+"""Untrusted input sources: web frameworks, CLI and stdin.
+
+Sources are matched three ways:
+1. Resolved dotted names (`flask.request.args`, `sys.argv`, builtin `input`).
+2. Request-object parameters: a parameter named `request`/`req` (Django, DRF, Starlette,
+   FastAPI `Request`) whose request-data attributes are read.
+3. Route handler parameters: every parameter of a function decorated with a routing
+   decorator (`@app.route`, `@app.get`, `@router.post`, ...) is client-controlled
+   (Flask path variables, FastAPI path/query/body parameters).
+"""
+
+from __future__ import annotations
+
+import ast
+
+# Attributes of `flask.request` that carry client data.
+FLASK_REQUEST_ATTRS = frozenset(
+    {
+        "args",
+        "form",
+        "values",
+        "json",
+        "data",
+        "cookies",
+        "headers",
+        "files",
+        "get_json",
+        "get_data",
+        "view_args",
+        "path",
+        "full_path",
+        "url",
+        "query_string",
+        "stream",
+    }
+)
+
+# Attributes of a request parameter (Django/DRF/Starlette/FastAPI) that carry client data.
+REQUEST_PARAM_ATTRS = frozenset(
+    {
+        # Django
+        "GET",
+        "POST",
+        "body",
+        "COOKIES",
+        "META",
+        "FILES",
+        "headers",
+        "path",
+        "path_info",
+        # DRF
+        "data",
+        "query_params",
+        # Starlette / FastAPI
+        "path_params",
+        "cookies",
+        "json",
+        "form",
+        "url",
+        # Flask-style, when a request object is passed around
+        "args",
+        "values",
+        "get_json",
+        "get_data",
+    }
+)
+REQUEST_PARAM_NAMES = frozenset({"request", "req"})
+
+# Fully-qualified names whose value (attribute) or return value (call) is untrusted.
+SOURCE_NAMES = {
+    "sys.argv": "command-line arguments (sys.argv)",
+    "sys.stdin": "standard input (sys.stdin)",
+    "input": "user input (input())",
+    "builtins.input": "user input (input())",
+}
+
+# Decorator method names that register an HTTP route handler.
+ROUTE_DECORATORS = frozenset(
+    {"route", "get", "post", "put", "patch", "delete", "head", "options", "api_route", "websocket"}
+)
+
+
+def flask_request_source(resolved: str) -> str | None:
+    """`flask.request.args` -> description, for any resolved dotted name."""
+    prefix = "flask.request."
+    if resolved.startswith(prefix):
+        attr = resolved[len(prefix) :].split(".", 1)[0]
+        if attr in FLASK_REQUEST_ATTRS:
+            return f"Flask request data (request.{attr})"
+    return None
+
+
+def is_route_handler(func: ast.AST) -> bool:
+    """Decorated with `@<obj>.route(...)`, `@<obj>.get(...)`, etc."""
+    for deco in getattr(func, "decorator_list", ()):
+        target = deco.func if isinstance(deco, ast.Call) else deco
+        if isinstance(target, ast.Attribute) and target.attr in ROUTE_DECORATORS:
+            return True
+    return False

hackscan-0.1.0.dist-info/METADATA

@@ -0,0 +1,181 @@
+Metadata-Version: 2.5
+Name: hackscan
+Version: 0.1.0
+Summary: Python SAST orchestrator: own AST + taint engine, imports Semgrep/Bandit/CodeQL/Gitleaks, dedupes, emits SARIF.
+Project-URL: Source, https://github.com/kahledawad2019-netizen/hackscan
+Project-URL: Issues, https://github.com/kahledawad2019-netizen/hackscan/issues
+License-Expression: MIT
+License-File: LICENSE
+Keywords: sarif,sast,security,static-analysis,taint-analysis,vulnerability-scanner
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security
+Classifier: Topic :: Software Development :: Quality Assurance
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: pyyaml>=6.0.3
+Description-Content-Type: text/markdown
+
+# 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.
+
+```text
+$ 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?
+
+| | HackScan |
+|---|---|
+| **Verdicts, not just matches** | Every injection candidate is **confirmed** (untrusted source reaches it, with a trace), **suppressed** (provably constant or sanitized on every path), or left as a **candidate** for review. |
+| **Sound suppression** | A finding is only dismissed if *every* path is safe. Branches, loops (`break`/`continue`), `try`/`except`/`finally`, aliasing and mutation of lists/dicts, closures and `:=` are modeled. A differential fuzzer executes thousands of random programs to check that no dismissed sink ever receives attacker input. |
+| **Framework-aware** | Sources: Flask `request.*`, Django/DRF/Starlette/FastAPI request objects (incl. `self.request`), route-handler parameters, `input()`, `sys.argv`. |
+| **One report from many tools** | Imports Semgrep, Bandit, CodeQL (SARIF) and Gitleaks; deduplicates by vulnerability class and location, keeping every tool as provenance. |
+| **CI-ready** | SARIF 2.1.0 (validated against the OASIS schema) for GitHub code scanning, `--fail-on` exit codes, stable fingerprints that survive code moves. |
+
+## Install
+
+```bash
+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
+
+```bash
+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
+```
+
+| Option | Meaning |
+|---|---|
+| `--severity`, `--min-confidence` | Report filters. |
+| `--fail-on SEV` | Exit 1 if an open (candidate/confirmed) finding is at least `SEV`. Suppressed findings never count. |
+| `--ignore GLOB` | Skip paths (`tests/*`, `**/migrations/**`, `legacy`). `.venv`, `node_modules`, `build`, ... are always skipped. |
+| `--with TOOLS` / `--import FMT=FILE` | Run external tools / import reports (`sarif`, `semgrep`, `bandit`, `codeql`, `gitleaks`). A missing or failing tool is a warning unless `--strict-tools`. |
+| `-o FILE` | Write the report to `FILE`. Never overwrites anything except a previous HackScan report. |
+| `--plugins DIR` | Load custom rules (see below). |
+| `--allow-incomplete` | Do not exit 2 when some files cannot be analyzed (they are still listed). |
+| `--no-taint` | Pattern matching only. |
+| `--jobs N` | Worker processes (default: automatic). |
+
+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.
+
+```yaml
+ignore: [tests/*, "**/migrations/**"]
+severity: medium
+min-confidence: 40
+fail-on: high
+with: [bandit]
+import:
+  codeql: codeql-results.sarif
+plugins: security/rules
+```
+
+### Suppressing a finding
+
+```python
+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
+
+| Rule | Detects | Severity |
+|---|---|---|
+| `HS-SQLI-001` | Non-constant SQL reaching DB-API `execute*`, Django `raw`, SQLAlchemy `text`, pandas `read_sql` | high |
+| `HS-CMDI-001` | Non-constant commands reaching `os.system`, `os.popen`, `subprocess.*(shell=True)`, ... | high |
+| `HS-CODEI-001` | Non-constant input to `eval`, `exec`, `compile` | high |
+| `HS-CRYPTO-001` | MD5/SHA-1 (unless `usedforsecurity=False`) | low |
+
+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
+
+```python
+# 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
+
+```yaml
+- 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
+
+```bash
+uv sync --group dev
+uv run pytest
+uv run ruff check . && uv run ruff format --check .
+```
+
+See [PROJECT.md](PROJECT.md) for the design, milestones and decision log.
+
+## License
+
+MIT

hackscan-0.1.0.dist-info/RECORD

@@ -0,0 +1,38 @@
+hackscan/__init__.py,sha256=GcNLXUbJFNBS3K-SvHhkLUK9cOMWVGY1ZeZt48qjt2w,78
+hackscan/cli.py,sha256=3UJJrJ6YHsTZsfve08xlgFecuU8FsV9mA3imd7pWcik,12878
+hackscan/config.py,sha256=mzer8CtjwdxQutrtmMS14k66USLjxDXZzLzSSWRycBs,6547
+hackscan/analyzers/__init__.py,sha256=elBA2v6nafQUQNdepIOzhnF1dfJNpdIM1r7_u7TYkII,23
+hackscan/analyzers/ast_pass.py,sha256=z9m7zhJyILLNWOWn3kmNHy8yn6rwYjR-4kiBx79pWag,6056
+hackscan/analyzers/suppressions.py,sha256=hcKBlK6729DZT3cFmW3p42RzFtvi3Nh93tneQjtkAKQ,2303
+hackscan/analyzers/taint_pass.py,sha256=xxU39JD7m1hZu3mzj41SCd2warHMaFUzjh5_hzBfQlc,34350
+hackscan/core/__init__.py,sha256=PCIydZsEkHbAAwx6huzlLKZIjZVwdN3zmYzzDGUiApo,60
+hackscan/core/dedupe.py,sha256=Fs58QHoTUIqvhwTGDHWM_y8exDfQXJWXhE9k_tu7VCQ,5787
+hackscan/core/fingerprint.py,sha256=dnzay8zrqXi7RZzJzE-J8a535Gf3HBwgFtLYD691wx8,2561
+hackscan/core/models.py,sha256=Drv92BkGGP161f7eHrkYk3Bc0iYnJ6VNz5uW6T80f7I,9284
+hackscan/core/pipeline.py,sha256=Okjh1IybZgjh86h7DBJ5GG78DZ2nNbre8myv5uIQfCo,6241
+hackscan/core/redact.py,sha256=dJN7RC01yVP_1IrOHeJ0IzobNQJlBCSdQ2mVgeuGArg,3405
+hackscan/core/taxonomy.py,sha256=ry_x7K3z9rh1AY5W7q7Fjib9OSMG2YYeAKEC9gEEwLs,3268
+hackscan/importers/__init__.py,sha256=fuGmHD8qS_xDk57KLCkDO4fZLXHraaNnAtE3MdV5pb0,49
+hackscan/importers/common.py,sha256=JE1BhKNTTHnJefadNMqUcjca01DwbhkUVad6s9qCZTg,7577
+hackscan/importers/gitleaks.py,sha256=aWzi2zjHy1VCoVaB6QxruW0U2qzbl9MiVRgBd3z53tM,3789
+hackscan/importers/runner.py,sha256=w66aWDa_lECGekNOsKDIzu1fzATJeuceY92IPIEUJ4A,5937
+hackscan/importers/sarif.py,sha256=L0bvKQUqCxw3weEsLgNoRFXVU-xVzH0QGapPV_uJ5Vo,5931
+hackscan/plugins/__init__.py,sha256=ftL30V67HM7IlVwdZ75Diajl6O0KlW896xQzuS6UsGM,197
+hackscan/plugins/base.py,sha256=nmXhLmApn3iaHId8sovOUU5WjwBiVmc8rg5hufYjhTY,10198
+hackscan/plugins/loader.py,sha256=cWS79msmrMV1SBqj8coIqj6UI3UCM7Hbn1WMy0V6uGU,3926
+hackscan/plugins/scopes.py,sha256=4GDUAdxalzcq8pEuoXxu9ougMA_YMh0UYipzmUjvGBg,11484
+hackscan/plugins/rules/__init__.py,sha256=QlFidHeq30_8JfoB4PMxjrGQfQGeYohdZQdQ3cMUTgw,32
+hackscan/plugins/rules/cmdi.py,sha256=KtU0DZIxLHdyP7tc6_SVS2Q3F7y8Lf4MDLo9kYuO5jo,2420
+hackscan/plugins/rules/codei.py,sha256=9uBSpWdU1l_eoOEWhU5jBCpJSjKb00HWT5WwYXDIciw,1503
+hackscan/plugins/rules/sqli.py,sha256=7-5Ab-wKGf3E4Pl7OwwJfEP9q8NjlKli8P5tzergghA,4184
+hackscan/plugins/rules/weak_crypto.py,sha256=Ikfbkf1iMXi4YG319FFwXjR_-n3M30KyP6YpyZIy1Ak,1952
+hackscan/sarif/__init__.py,sha256=pvckjpJyukYgJmh_K2k8McH0xr5sVOSdQ2ExwnhHPXM,26
+hackscan/sarif/generator.py,sha256=RadNx_1-dL6uDptfHQXSuIO1EjuBjm_WJbXC4n-PzVg,7898
+hackscan/taint/__init__.py,sha256=LtqvgHY01Ya-lIis87zVxBbaz8OwGm-_SR6b8tz-YIg,44
+hackscan/taint/sanitizers.py,sha256=Edqvr5UFyAFBKWilhxGgz2es2z8aXhjd37nGhtOPjNo,1396
+hackscan/taint/sources.py,sha256=LSskC0JKwxbIsiyXU2Prz0sCyYQmGfsZQLqdBUQ11zU,2883
+hackscan-0.1.0.dist-info/METADATA,sha256=J3YB65Kqr-VpQaDLQI-c-DU4F6TefIJr2XkKGCB0Rh4,7702
+hackscan-0.1.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+hackscan-0.1.0.dist-info/entry_points.txt,sha256=MwyZQj1nZ-7l0tUv-x1CtLeryBbtnOleUZihDy6Fgxs,47
+hackscan-0.1.0.dist-info/licenses/LICENSE,sha256=KkO2hUXEuGbXW1_AnaHLlx2GHIdQA8UmxOXLNay7yW8,1068
+hackscan-0.1.0.dist-info/RECORD,,

hackscan-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.4
+Root-Is-Purelib: true
+Tag: py3-none-any

hackscan-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+hackscan = hackscan.cli:main

hackscan-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Khaled Awad
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.