drheaderplus 3.0.0__tar.gz

drheaderplus-3.0.0/.dockerignore

@@ -0,0 +1,106 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+reports/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# jetbrains
+.idea/

drheaderplus-3.0.0/.editorconfig

@@ -0,0 +1,24 @@
+# http://editorconfig.org
+
+root = true
+
+[*]
+indent_style = space
+indent_size = 4
+trim_trailing_whitespace = true
+insert_final_newline = true
+charset = utf-8
+end_of_line = lf
+
+[.github/**/*.yml]
+indent_size = 2
+
+[*.bat]
+indent_style = tab
+end_of_line = crlf
+
+[LICENSE]
+insert_final_newline = false
+
+[Makefile]
+indent_style = tab

drheaderplus-3.0.0/.github/FUNDING.yml

@@ -0,0 +1,3 @@
+# These are supported funding model platforms
+
+custom: 'https://www.santandertechnology.co.uk'

drheaderplus-3.0.0/.github/ISSUE_TEMPLATE

@@ -0,0 +1,15 @@
+* drHEADer version:
+* Python version:
+* Operating System:
+
+### Description
+
+Describe what you were trying to get done.
+Tell us what happened, what went wrong, and what you expected to happen.
+
+### What I Did
+
+```
+Paste the command(s) you ran and the output.
+If there was a crash, please include the traceback here.
+```

drheaderplus-3.0.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,48 @@
+# Thank you for contributing to DrHeader !
+
+To help keep changes flowing in and avoid potential merging headaches we have created this form. 
+
+Please fill it in if you can or feel free to ask questions , we don't want this to be a barrier.
+
+Please trim above here.
+
+## Proposed changes
+
+Please describe your changes here
+
+## Type of change
+
+What types of changes do you want to introduce to DrHeader?
+
+- [ ] Bugfix (non-breaking change which fixes an issue)
+- [ ] New feature (non-breaking change which adds functionality)
+- [ ] Breaking change 
+- [ ] Documentation Update
+- [ ] Test Update
+- [ ] Rules Update 
+- [ ] Other (please describe)
+
+Please ensure your pull request adheres to the following guidelines:
+- [ ] A Github Issue that explains the work.
+- [ ] The changes are in a branch that is reasonably up to date
+- [ ] Tests are provided to reasonably cover new or altered functionality.
+- [ ] Documentation is provided for the new or altered functionality.
+- [ ] You have the legal right to give us this code.
+- [ ] You have adhered to the CoC
+
+## Link to the github issue 
+
+https://github.com/Santandersecurityresearch/DrHeader/issues/
+
+## Tests you have added 
+
+testclass.method_name()  
+
+## Tests you have altered
+
+testclass.method_name()
+
+## Anything Else 
+
+
+Thanks for getting this far !

drheaderplus-3.0.0/.github/dependabot.yml

@@ -0,0 +1,23 @@
+version: 2
+updates:
+- package-ecosystem: "pip"
+  directory: "/"
+  versioning-strategy: "lockfile-only"
+  schedule:
+    interval: "daily"
+  target-branch: "develop"
+  reviewers:
+    - "danielcuthbert"
+    - "javixeneize"
+    - "pealtrufo"
+    - "emilejq"
+- package-ecosystem: "github-actions"
+  directory: "/"
+  schedule:
+    interval: "weekly"
+  target-branch: "develop"
+  reviewers:
+    - "danielcuthbert"
+    - "javixeneize"
+    - "pealtrufo"
+    - "emilejq"

drheaderplus-3.0.0/.github/workflows/codeql-analysis.yml

@@ -0,0 +1,37 @@
+name: CodeQL
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - main
+  schedule:
+    - cron: "24 23 * * 5"
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        language:
+          - python
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v5
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v3
+        with:
+          languages: ${{ matrix.language }}
+
+      - name: Autobuild
+        uses: github/codeql-action/autobuild@v3
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v3

drheaderplus-3.0.0/.github/workflows/pull_request.yml

@@ -0,0 +1,53 @@
+name: Scan pull request
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Run lint scan
+        run: uv run ruff check .
+
+      - name: Run SAST scan
+        run: uv run ruff check ./drheader --select S
+
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version:
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: ${{ matrix.python-version }}
+          enable-cache: true
+
+      - name: Run tests
+        run: uv run pytest --cov=drheader --cov-fail-under=80 --junitxml results.xml
+
+      - name: Upload test results
+        uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: results-${{ matrix.python-version }}
+          path: results.xml

drheaderplus-3.0.0/.github/workflows/release.yml

@@ -0,0 +1,36 @@
+name: Create release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write
+      id-token: write
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v5
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v7
+        with:
+          python-version: "3.12"
+
+      - name: Build release artifacts
+        run: uv build
+
+      - name: Create GitHub release
+        uses: ncipollo/release-action@v1
+        with:
+          artifacts: dist/*
+          generateReleaseNotes: true
+
+      # TODO (Phase 4): Set up trusted publishing on PyPI, then uncomment:
+      # - name: Publish to PyPI
+      #   run: uv publish

drheaderplus-3.0.0/.gitignore

@@ -0,0 +1,115 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# local development files
+.claude/
+.vscode/
+work_docs/
+
+# Distribution / packaging
+.Python
+env/
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+.hypothesis/
+.pytest_cache/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+docs/_static/*
+!docs/_static/.keep
+
+# PyBuilder
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# pyenv
+.python-version
+
+# celery beat schedule file
+celerybeat-schedule
+
+# SageMath parsed files
+*.sage.py
+
+# dotenv
+.env
+
+# virtualenv
+.venv
+venv/
+ENV/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+
+# jetbrains
+.idea/
+
+# junit reports folder
+reports

drheaderplus-3.0.0/CLI.md

@@ -0,0 +1,242 @@
+![drHEADer](assets/img/hero.png)
+
+# CLI Usage
+This page describes how to use the drHEADer command line interface.
+
+## Contents
+* [Analysing Headers Locally](#analysing-headers-locally)
+  * [Bulk Scanning](#bulk-scanning)
+  * [Scan Options](#scan-options)
+* [Scanning Remote Endpoints](#scanning-remote-endpoints)
+  * [Configuring the HTTP Request](#configuring-the-http-request)
+  * [Bulk Scanning](#bulk-scanning-1)
+    * [File Input Format](#file-input-format)
+    * [Configuring the HTTP Request](#configuring-the-http-request-1)
+  * [Scan Options](#scan-options-1)
+* [Report Output](#report-output)
+
+## Analysing Headers Locally
+You can validate a set of headers against a drHEADer ruleset using the `compare single` command:
+```shell
+$ drheader compare single [SCAN_OPTIONS] FILE
+```
+
+This will parse the contents of `FILE`, analyse the headers within it against a drHEADer ruleset, and report back any
+rule violations. `FILE` is the path to a JSON file containing the headers to be analysed.
+
+### Bulk Scanning
+You can validate several sets of headers at once using the `compare bulk` command:
+```shell
+$ drheader compare bulk [SCAN_OPTIONS] FILE
+```
+
+The contents of `FILE` must be a JSON array with each item specifying a set of headers to be analysed and an associated
+endpoint:
+
+```json
+  [
+    {
+        "url": "https://example.com",
+        "headers": {
+            "Cache-Control": "private, must-revalidate",
+            "Content-Security-Policy": "default-src 'self'; script-src 'unsafe-inline'"
+        }
+    },
+    {
+        "url": "https://example.net",
+        "headers": {
+            "Referrer-Policy": "strict-origin",
+            "Strict-Transport-Security": "max-age=31536000; preload",
+            "X-Content-Type-Options": "nosniff"
+        }
+    }
+  ]
+```
+
+You can view the JSON schema for bulk scanning with `compare` [here](drheader/resources/cli/bulk_compare_schema.json).
+
+### Scan Options
+This table lists the scan options available when using the `compare` command:
+
+| Option                     | Shorthand Option | Description                                                 |
+|:---------------------------|:-----------------|:------------------------------------------------------------|
+| `--cross-origin-isolated`  | `-co`            | Enable cross-origin isolation validations ¹                 |
+| `--debug`                  | `-d`             | Enable debug logging                                        |
+| `--junit`                  | `-j`             | Generate a JUnit report *(not available for bulk scanning)* |
+| `--merge`                  | `-m`             | Merge a custom ruleset with the default rules               |
+| `--output [json \| table]` | `-o`             | Report output format  [default: table]                      |
+| `--rules-file FILENAME`    | `-rf`            | Use a custom ruleset, loaded from file ²                    |
+| `--rules-uri URI`          | `-ru`            | Use a custom ruleset, downloaded from URI ²                 |
+
+¹ Cross-origin isolation validations are opt-in. See [Cross-Origin Isolation](README.md#cross-origin-isolation).
+
+² For information on defining a custom ruleset see [RULES](RULES.md).
+
+## Scanning Remote Endpoints
+You can scan a remote endpoint using the `scan single` command:
+
+```shell
+$ drheader scan single [SCAN_OPTIONS] TARGET_URL [REQUEST_ARGS]
+```
+
+This will send an HTTP `HEAD` request to `TARGET_URL`, validate the headers that are returned in the response and report
+back any rule violations.
+
+### Configuring the HTTP Request
+Internally, drHEADer uses the [`requests`](https://requests.readthedocs.io/en/latest/) package to make the HTTP call,
+and you can customise the request with the same configuration options that can be processed by this package. Any
+arguments received in `[REQUEST_ARGS]` will be propagated to the HTTP call. This means, you can for instance...
+
+* Change the request method:
+    ```shell
+    $ drheader scan single https://example.com --method POST
+    ```
+
+* Send request parameters:
+    ```shell
+    $ drheader scan single https://example.com --params '{"name": "h_simpson", "department": "Sector 7G"}'
+    ```
+
+* Send data in the request body:
+    ```shell
+    $ drheader scan single https://example.com --json '{"number": "42", "street": "Wallaby Way", "city": "Sydney"}'
+    ```
+
+* Configure the timeout on the request:
+    ```shell
+    $ drheader scan single https://example.com --timeout 30
+    $ drheader scan single https://example.com --timeout '(5, 30)'
+    ```
+
+* Configure SSL verification:
+    ```shell
+    $ drheader scan single https://example.com --verify false
+    $ drheader scan single https://example.com --verify 'path/to/ca/bundle'
+    ```
+
+See the [requests](https://requests.readthedocs.io/en/latest/_modules/requests/api/#request) documentation for a full
+list of options.
+
+### Bulk Scanning
+You can scan several endpoints at once using the `scan bulk` command:
+```shell
+$ drheader scan bulk [SCAN_OPTIONS] FILE
+```
+
+The contents of `FILE` must be a JSON array with each item specifying a URL to target and additional request args:
+```json
+[
+    {
+        "url": "https://example.com"
+    },
+    {
+        "url": "https://example.net"
+    },
+    {
+        "url": "https://example.org"
+    }
+]
+```
+
+You can view the JSON schema for bulk scanning with `scan` [here](drheader/resources/cli/bulk_scan_schema.json). See
+[configuring the HTTP request](#configuring-the-http-request-1) for details on request args.
+
+#### File Input Format
+The default input format for `FILE` is JSON, which allows you to configure more complex HTTP requests (see
+[configuring the HTTP request](#configuring-the-http-request-1)). If you only want to target each endpoint with a basic
+HTTP HEAD request and no additional configuration, you can choose to pass the input file in a simpler `.txt` format by
+specifying the `-ff` (file format) option:
+
+```shell
+$ drheader scan bulk -ff txt FILE
+```
+
+Each endpoint must be on a separate line:
+```
+https://example.com
+https://example.net
+https://example.org
+```
+
+#### Configuring the HTTP Request
+For bulk scanning, [request args](#configuring-the-http-request) are configured on a per-target basis in the JSON file:
+```json
+[
+    {
+        "url": "https://example.com",
+        "method": "POST"
+    },
+    {
+        "url": "https://example.net",
+        "params": {
+            "name": "h_simpson",
+            "department": "Sector 7G"
+        }
+    },
+    {
+        "url": "https://example.org",
+        "json": {
+            "number": "42",
+            "street": "Wallaby Way",
+            "city": "Sydney"
+        },
+        "timeout": 30,
+        "verify": false
+    }
+]
+```
+
+See the [requests](https://requests.readthedocs.io/en/latest/_modules/requests/api/#request) documentation for a full
+list of options.
+
+### Scan Options
+This table lists the scan options available when using the `scan` command:
+
+| Option                        | Shorthand Option | Description                                                 |
+|:------------------------------|:-----------------|:------------------------------------------------------------|
+| `--cross-origin-isolated`     | `-co`            | Enable cross-origin isolation validations ¹                 |
+| `--debug`                     | `-d`             | Enable debug logging                                        |
+| `--file-format [json \| txt]` | `-ff`            | FILE input format  [default: json] *(bulk scanning only)*   |
+| `--junit`                     | `-j`             | Generate a JUnit report *(not available for bulk scanning)* |
+| `--merge`                     | `-m`             | Merge a custom ruleset with the default rules               |
+| `--output [json \| table]`    | `-o`             | Report output format  [default: table]                      |
+| `--rules-file FILENAME`       | `-rf`            | Use a custom ruleset, loaded from file ²                    |
+| `--rules-uri URI`             | `-ru`            | Use a custom ruleset, downloaded from URI ²                 |
+
+¹ Cross-origin isolation validations are opt-in. See [Cross-Origin Isolation](README.md#cross-origin-isolation).
+
+² For information on defining a custom ruleset see [RULES](RULES.md).
+
+## Report Output
+By default, results will be output in a tabulated format:
+
+```
+https://example.com: 9 issues found
+----
+ rule      | Cache-Control
+ message   | Value does not match security policy
+ severity  | high
+ value     | max-age=604800
+ expected  | ['no-store', 'max-age=0']
+ delimiter | ,
+----
+ rule     | Content-Security-Policy
+ message  | Header not included in response
+ severity | high
+----
+ rule     | Pragma
+ message  | Header not included in response
+ severity | high
+ expected | ['no-cache']
+```
+
+You can change this using the `--output` option. Currently, the only other supported option is JSON:
+```sh
+$ drheader scan single --output json
+```
+
+In order to save scan results, you can pipe the JSON output to [jq](https://stedolan.github.io/jq/), which is a
+lightweight and flexible command-line JSON processor:
+```sh
+$ drheader scan single --output json https://example.com | jq '.'
+```