django-security-hunter 0.5.0

 ____    ____    _   _ 
|  _ \  / ___|  | | | |
| | | | \___ \  | |_| |
| |_| |  ___) | |  _  |
|____/  |____/  |_| |_|

[!TIP] New here? Use Install and run below, then Quick start and CI when you automate.

[!IMPORTANT] Why teams choose this tool: one CLI for Django+DRF checks, CI-friendly exit codes, and SARIF output for GitHub Security tab visibility.

Install and run

This package is a standalone CLI (it does not register a manage.py subcommand). From your Django project root (the directory that contains manage.py):

pip install django-security-hunter
django_security_hunter scan --project . --settings yourproject.settings --allow-project-code --format console

Quick copy (short flags):

djangoguard scan -p . -s yourproject.settings -y -f console

--allow-project-code confirms that you allow the tool to load and execute project code paths (for example, Django settings import side effects). Use it only for repositories you trust/control.

Replace yourproject.settings with the same module you use for DJANGO_SETTINGS_MODULE (for example config.settings or mysite.settings). Omitting --settings still runs many file-based checks, but Django settings rules (e.g. DEBUG, SECRET_KEY, ALLOWED_HOSTS, HTTPS cookies) are skipped.

Shorthand CLI name: djangoguard (same program).

Optional: write reports to disk as JSON or SARIF (for GitHub Code Scanning):

django_security_hunter scan --project . --settings yourproject.settings --allow-project-code --format json --output reports/scan.json
django_security_hunter scan --project . --settings yourproject.settings --allow-project-code --format sarif --output reports/scan.sarif

PyPI Project links (Homepage, Source, Issues, Documentation, Changelog) come from [project.urls] in pyproject.toml and point at this repo so you can star, fork, or open PRs on GitHub.

At a glance: what gets checked

High-level checklist of what the scanner looks for (details and rule IDs: docs/rules.md and What it finds):

Django production settings

• DEBUG, SECRET_KEY, ALLOWED_HOSTS
• HTTPS redirect, HSTS, secure session / CSRF cookies
• SECURE_CONTENT_TYPE_NOSNIFF, X_FRAME_OPTIONS
• CSRF_TRUSTED_ORIGINS, CORS configuration (CORS_ALLOW_ALL_ORIGINS, allowlists)
• Very large request / upload limits (DoS-style misconfiguration)

Django REST Framework

• Default permission and authentication classes (e.g. missing vs AllowAny)
• Throttling disabled or weak for auth-like routes (urls.py heuristics)
• Serializers with fields = "__all__" (extra scrutiny on sensitive-looking serializer names)
• Global list pagination and upload-related settings
• Per-view AllowAny on DRF-style classes (review hint, not full authz proof)

Static analysis (Python + templates)

• XSS-prone patterns (mark_safe, SafeString, disabling template auto-escaping)
• SSRF-style outbound HTTP when the URL is not a fixed string (heuristic)
• Risky deserialization and eval / exec
• Secrets in logging calls and hardcoded secret-like names
• SQL injection hints (heuristic): non-literal SQL passed to execute / executemany, RawSQL(...), or Model.objects.raw(...) (DJG075)

Models, concurrency, performance

• Natural-key / identifier fields without uniqueness; risky CASCADE edges
• Race-prone ORM patterns, missing transaction.atomic, counters without F() / locking
• Per-test query count, repeated SQL shapes, DB time (profile mode); static N+1-style hints

Optional integrations

• pip-audit (vulnerable dependencies), Bandit, Semgrep (enable in config or environment)

Why django_security_hunter

AI-assisted coding speeds up delivery but can hide risky backend patterns. This tool gives fast, actionable feedback in the editor and in CI, before code ships.

What it finds

django-security-hunter combines loaded Django settings (when you pass --settings), static analysis of Python and HTML templates, optional pytest-based query profiling, and optional pip-audit / Bandit / Semgrep. Findings use stable rule IDs (DJG001 … DJG062); the full catalog with severities and fix hints is in docs/rules.md.

Below is what each area is meant to catch. Most rules are heuristic—useful for triage, not a substitute for manual review or penetration testing.

Django settings (settings.py and related)

Django REST Framework (API surface)

Static code patterns (.py and templates)

Models, concurrency, and performance

Dependencies and external scanners (optional)

What is not a built-in guarantee

• SQL injection: DJG075 is heuristic (syntax-level only): it does not trace data from request to database. Safe uses like cursor.execute(sql, params) where sql is built in a trusted module may still WARN. For deeper coverage, use the ORM, parameterized queries, and optional Semgrep / Bandit rulesets.
• Authorization: DJG027 flags permissive DRF permissions; it does not prove or disprove object-level access control.
• False positives / negatives: documented per rule in docs/rules.md; tune --threshold and optional scanners for your risk appetite.

Features

Feature cards (quick view)

• Secure-by-default checks: Django settings, DRF defaults, static security patterns, and model integrity hints in one run.
• CI-ready output: human console output for devs and SARIF for GitHub Security tab workflows.
• Performance visibility: profile mode surfaces query count, duplicate SQL, and DB time hotspots.
• Extensible scanning: optional pip-audit, Bandit, and Semgrep integration when teams need deeper coverage.

Documentation

Requirements

• Python 3.11+
• Django 4.2+ (declared dependency)
• Profile mode: pytest in the target project; pytest-django recommended for ORM tests

Installation

PyPI

pip install django-security-hunter

• Import name: django_security_hunter
• CLI: django_security_hunter or djangoguard (same entry point)

From source (folder name can match your clone):

git clone https://github.com/abu-rayhan-alif/djangoSecurityHunter.git django-security-hunter
cd django-security-hunter
python -m venv .venv
# Windows PowerShell
.venv\Scripts\Activate.ps1
# Linux / macOS
# source .venv/bin/activate
pip install -e ".[dev]"

Quick start

30-second quickstart

pip install django-security-hunter
djangoguard scan -p . -s mysite.settings -y -f console

If findings at or above your threshold should fail CI:

djangoguard scan -p . -s mysite.settings -y -f sarif -o reports/scan.sarif -t HIGH

Track score trend across runs:

djangoguard scan -p . -s mysite.settings -y -f json --trend-history reports/trend.json -o reports/scan.json

You need: a terminal, Python 3.11+, and a Django project folder that contains manage.py.

1. Install the tool

   pip install django-security-hunter
   

2. Go to your project root (same folder as manage.py).

3. Run a scan — replace mysite.settings with your real settings module (the same string you use for DJANGO_SETTINGS_MODULE):

   django_security_hunter scan --project . --settings mysite.settings --allow-project-code --format console
   

   Without --settings, many checks still run on your Python files, but Django settings checks (e.g. DEBUG, SECRET_KEY, ALLOWED_HOSTS) are skipped.

4. Save a report to a file (optional):

   django_security_hunter scan --project . --settings mysite.settings --allow-project-code --format json --output reports/scan.json
   django_security_hunter scan --project . --settings mysite.settings --allow-project-code --format sarif --output reports/scan.sarif
   

5. Fail CI when something serious is found — add --threshold HIGH (or WARN / CRITICAL). If any finding is at or above that level, the command exits with code 2.

   django_security_hunter scan --project . --settings mysite.settings --allow-project-code --threshold HIGH --format console
   

Commands

django_security_hunter scan

Static and configuration analysis; writes a report in the chosen format.

django_security_hunter profile

Static heuristics (e.g. DJG045) plus, by default, a nested pytest run with django_security_hunter.profile_pytest, recording per-test query count, SQL time, and repeated SQL signatures (DJG040–DJG042 / DJG041). Thresholds: query_count_threshold, db_time_ms_threshold in config.

django_security_hunter profile --project . --settings mysite.settings --allow-project-code --format console

Short form:

django_security_hunter scan -p . -s mysite.settings -y -f console

django_security_hunter init

Creates djangoguard.toml with defaults (skipped if djangoguard.toml or legacy django_security_hunter.toml already exists).

Environment variables

If unset for pip-audit/Bandit/Semgrep, use pip_audit / bandit / semgrep in djangoguard.toml or enable_* aliases (see Configuration).

Configuration

Files (later overrides earlier)

1. pyproject.toml → [tool.django_security_hunter]
2. pyproject.toml → [tool.djangoguard]
3. django_security_hunter.toml in project root
4. djangoguard.toml in project root (highest precedence)

Example

severity_threshold = "WARN"
query_count_threshold = 50
db_time_ms_threshold = 200
# pip_audit = true
# bandit = true
# semgrep = true
# score_weight_info = 1
# score_weight_warn = 5
# score_weight_high = 15
# score_weight_critical = 40
# Legacy aliases also work: enable_pip_audit, enable_bandit, enable_semgrep

CLI options

Short aliases: -p (--project), -s (--settings), -f (--format), -o (--output), -t (--threshold), -y (--allow-project-code).

Rule highlights

Full list: docs/rules.md.

Output formats

• Console — human-readable; Rich panels on a TTY when enabled.
• JSON — includes schema_version: django_security_hunter.report.v1 for stable parsing.
• SARIF — v2.1.0, GitHub-friendly (columnKind, safe artifact URIs).

Exit codes

Use in GitHub / GitLab CI

[!NOTE] pip install only installs the command-line tool. It does not create .github/workflows or .gitlab-ci.yml for you. You copy a small YAML file once, then every push can run the scan automatically.

This repository (developers of django-security-hunter)

Our own CI is in .github/workflows/ci.yml. For SARIF and the Security tab, see docs/github_code_scanning.md.

Your Django project on GitHub Actions

Do this in your app’s GitHub repo (not in this tool’s repo):

1. Create the folder .github/workflows/ if it does not exist.
2. Copy examples/ci/github-actions-django-app.yml into that folder, e.g. as django-security-hunter.yml.
3. Open the file and change yourproject.settings to your real settings module (e.g. config.settings).
4. If the job needs your dependencies, uncomment the pip install -r requirements.txt line (or add your install steps).
5. Commit and push. Check the Actions tab — the workflow should run on push and pull requests.
6. Optional — block bad PRs: In GitHub → Settings → Branches → Branch protection, add a rule and enable Require status checks, then select this workflow’s check.

Your Django project on GitLab

1. Copy examples/ci/gitlab-ci.yml to the root of your repo as .gitlab-ci.yml.
2. Change yourproject.settings to your real settings module.
3. Commit and push. Open CI/CD → Pipelines to see the job.

Where the example files live

The YAML templates are in this repository under examples/ci/. They are not bundled inside the PyPI wheel; people usually copy them from GitHub or from a checkout of this repo.

Docker

docker build -t django_security_hunter:local .
docker run --rm django_security_hunter:local django_security_hunter scan --project /app --format console

docker compose run --rm django_security_hunter django_security_hunter scan --project /app --format console

Security notes

• The tool reads your project files and may spawn subprocesses (pytest, pip-audit, Bandit, Semgrep) when enabled. Use it on trusted trees; review CI secrets and third-party scanner configs.
• SARIF / JSON paths are normalized to reduce odd uri values in reports.
• Settings module names are validated before django.setup() to reduce injection-style mistakes.
• Automated scans (Bandit, etc.) report Low findings for expected subprocess use; there is no shell=True in those call sites.

Limitations

• Several rules are heuristic (false positives possible). DJG027 is not a full object-level authorization audit.
• Bandit / Semgrep are optional; first Semgrep run may fetch rule packs.
• Profile quality depends on pytest coverage and Django DB tests where relevant.

Roadmap / future work

• Deeper URLconf → view resolution and richer authz modeling
• Per-rule toggles in config
• Richer runtime evidence where tests allow

Contributing

1. Open an issue for large changes
2. Add tests for new rules
3. Keep rule IDs stable and documented in docs/rules.md
4. Include fix_hint on findings

License

MIT