Skip to content
BranchesTags

Repository files navigation

🛡️ Argus Header

Fast, lightweight HTTP security header analyzer built for developers, security engineers, and penetration testers.

Python Version License

Argus Header is a command-line tool that analyzes HTTP response headers and identifies common security misconfigurations, information leakage, and HTTP security best-practice issues. It scores each target from 0–100 with a letter grade and exports reports as JSON, Markdown, or HTML.

✨ Features

HTTP Request Engine

  • ✅ GET & HEAD request support
  • ✅ Configurable request timeout
  • ✅ Redirect handling
  • ✅ Retry mechanism
  • ✅ Multiple URL scanning
  • ✅ Parallel scanning

Security Analysis

Detects missing security headers including:

  • Content-Security-Policy (CSP)
  • Strict-Transport-Security (HSTS)
  • X-Frame-Options
  • X-Content-Type-Options

Security Score & Grade

  • Security Score from 0–100
  • Letter Grade from A–F
  • Risk level and penalty breakdown
  • Stable rule IDs for every finding (e.g. SEC-001, COOKIE-002)

Cookie Analysis

Analyzes Set-Cookie attributes:

  • Secure flag (MEDIUM)
  • HttpOnly flag (MEDIUM)
  • SameSite attribute (LOW)

Information Leakage Detection

Detects exposed:

  • Server
  • X-Powered-By

CORS Analysis

Detects:

  • Wildcard Access-Control-Allow-Origin: *

Performance Checks

Analyzes:

  • Cache-Control

Reports

  • Rich CLI output
  • Detailed --verbose mode
  • JSON report export (enhanced v0.7 schema)
  • Markdown report export
  • HTML report export (self-contained, escaped)
  • Severity levels
  • Security recommendations

🔍 Verbose Mode

The --verbose option provides a comprehensive scan report including:

  • Scan Information
  • Target Information
  • Request Configuration
  • Connection Information
  • HTTP Response Details
  • Redirect Information
  • Response Headers
  • Security Headers
  • Missing Security Headers
  • Present Security Headers
  • Information Leakage
  • Response Statistics
  • Findings Summary
  • Overall Assessment
  • End of Scan Summary

📦 Installation

Install from PyPI

pip install argus-header

Verify installation:

argus-header --version

Expected output:

Argus Header 0.7.0

Install from Source

git clone https://github.com/heyshreee/argus-header.git

cd argus-header

python -m venv .venv

Windows

.venv\Scripts\activate

Linux / macOS

source .venv/bin/activate

Install:

pip install -e .

🚀 Usage

Basic Scan

argus-header https://example.com

HEAD Request

argus-header https://example.com --method HEAD

Verbose Report

argus-header https://example.com --verbose

Custom Timeout

argus-header https://example.com --timeout 5

Multiple URLs

argus-header https://google.com https://github.com --parallel

Disable Redirects

argus-header https://example.com --no-redirect

Export JSON

argus-header https://example.com --json report.json

Security Score & Grade

argus-header https://example.com --score

Export Markdown Report

argus-header https://example.com --markdown report.md

Export HTML Report

argus-header https://example.com --html report.html

All Export Formats Together

argus-header https://example.com \
    --score \
    --json report.json \
    --markdown report.md \
    --html report.html

Display Version

argus-header --version

Display Help

argus-header --help

⚙️ Command Line Options

Option Description
--method HTTP Method (GET / HEAD)
--timeout Request timeout
--parallel Scan multiple URLs concurrently
--json FILE Save report as JSON (v0.7 enhanced schema)
--score Display the security score and grade
--markdown FILE Save a Markdown security report
--html FILE Save an HTML security report
--no-redirect Disable redirect following
--verbose Display detailed scan report
--version Display tool version
--help Show help information

📋 Example Output

$ argus-header https://example.com --score

   ___                             
  / _ | _______ _____ _____ _____  
 / __ |/ __/ _ `/ // (_-</(_-<(_-<  
/_/ |_/_/  \_, /\_,_/___/___/___/  
            /_/                    

 Argus Header
 HTTP Header Security Analyzer

Version: 0.7.0

╭──────── Scan Summary ────────╮
│ Target: https://example.com/ │
│ Status: 200                  │
│ Headers Found: 11            │
╰──────────────────────────────╯
                                     Analysis Findings                                     
┏━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Severity     ┃ Issue                     ┃ Risk                      ┃ Recommendation            ┃
┡━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ HIGH         │ Missing                   │ XSS (Cross-Site           │ Add a                     │
│              │ Content-Security-Policy   │ Scripting) attacks are    │ 'Content-Security-Policy' │
│              │                           │ easier to exploit.        │ header defining allowed   │
│              │                           │                           │ content sources.          │
│ HIGH         │ Missing                   │ Susceptible to            │ Add                       │
│              │ Strict-Transport-Security │ Man-in-the-Middle (MITM)  │ 'Strict-Transport-Securi… │
│              │                           │ protocol downgrade        │ max-age=63072000;         │
│              │                           │ attacks.                  │ includeSubDomains'.       │
│ HIGH         │ Missing X-Frame-Options   │ Vulnerable to             │ Add 'X-Frame-Options:     │
│              │                           │ Clickjacking attacks.     │ DENY' or 'SAMEORIGIN'.    │
│ MEDIUM       │ Missing                   │ Browsers may MIME-sniff   │ Add                       │
│              │ X-Content-Type-Options    │ the response body,        │ 'X-Content-Type-Options:  │
│              │                           │ leading to XSS.           │ nosniff'.                 │
│ LOW          │ Server Header Leaked:     │ Reveals server            │ Configure server to       │
│              │ cloudflare                │ technology, helping       │ suppress or obfuscate the │
│              │                           │ attackers verify CVEs.    │ 'Server' header.          │
│ LOW          │ Missing Cache-Control     │ Browser may not cache     │ Add 'Cache-Control'       │
│              │ Header                    │ resources efficiently,    │ header (e.g.,             │
│              │                           │ slowing load times.       │ max-age=3600).            │
└──────────────┴───────────────────────────┴───────────────────────────┴───────────────────────────┘

Tip: Run with --verbose to view detailed scan information.
╭─ Security Score ─╮
│ Score: 27/100    │
│ Grade: F         │
│ Risk: HIGH       │
│ Penalty: 73      │
╰──────────────────╯

🔐 Security Analysis

Security Headers

Checks for:

  • Content-Security-Policy
  • Strict-Transport-Security
  • X-Frame-Options
  • X-Content-Type-Options

Information Leakage

Checks for:

  • Server
  • X-Powered-By

CORS

Checks for:

  • Wildcard Access-Control-Allow-Origin

Performance

Checks for:

  • Cache-Control

📁 Project Structure

argus-header/

src/
└── argus_header/
    ├── __init__.py
    ├── __main__.py
    ├── analyzer.py        # rule engine with stable rule IDs
    ├── cookies.py         # Set-Cookie attribute analysis
    ├── scorer.py          # security score / grade engine
    ├── cli.py             # argument parsing & orchestration
    ├── reporter.py        # terminal output + canonical report + JSON export
    ├── markdown.py        # Markdown report renderer
    ├── html_report.py     # HTML report renderer
    ├── requester.py       # HTTP fetch engine (retries, redirects)
    ├── schemas.py         # Pydantic models for the API layer
    ├── utils.py           # URL normalization
    └── verbose.py         # 15-section detailed report

api.py                     # FastAPI service (GET/POST /analyze)
frontend/                  # vanilla JS dashboard with score panel & exports
tests/
docs/

README.md
CHANGELOG.md
CONTRIBUTING.md
LICENSE
pyproject.toml

🗺️ Roadmap

✅ v0.7.0 — Current Release

Added

  • Security Score (0–100) and Grade (A–F)
  • Risk level and penalty breakdown
  • Cookie analysis: Secure, HttpOnly, SameSite
  • Stable rule IDs for findings
  • Enhanced JSON reports with scan metadata
  • Markdown report export (--markdown)
  • HTML report export (--html)
  • CLI --score option
  • API score/grade/summary exposure
  • Dashboard score panel and finding summaries

🚀 v0.8.0 — Next

Planned features:

  • Expanded unit test coverage (CLI / verbose rendering)
  • GitHub Actions CI
  • Documentation improvements
  • Architecture improvements

🚀 v0.9.0

Planned features:

  • TLS Inspection
  • Certificate Analysis
  • HTTP/2 Detection
  • Advanced CORS Analysis

🎉 v1.0.0

  • Stable Public Release
  • Production-ready Documentation
  • Comprehensive Testing
  • Complete HTTP Security Analysis

💻 Development

Clone the repository:

git clone https://github.com/heyshreee/argus-header.git

cd argus-header

Install the development version:

python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

pip install -e .
pip install -r requirements-dev.txt

Run:

argus-header https://example.com

Run verbose mode:

argus-header https://example.com --verbose

Run the test suite and static checks:

pytest tests/ -v
ruff check src/ tests/
black --check src/ tests/
mypy src/

🤝 Contributing

Contributions are welcome.

  1. Fork the repository.

  2. Create a feature branch.

git checkout -b feature/my-feature
  1. Commit your changes.
git commit -m "feat: add awesome feature"
  1. Push your branch.
git push origin feature/my-feature
  1. Open a Pull Request.

Please read CONTRIBUTING.md before submitting major changes.

📄 License

Released under the MIT License.

See the LICENSE file for details.

👨‍💻 Author

Sriram

GitHub: https://github.com/heyshreee

PyPI: https://pypi.org/project/argus-header/

⚠️ Disclaimer

Argus Header is intended for defensive security, security auditing, learning, and authorized penetration testing only.

Only scan systems that you own or have explicit permission to assess.

The author is not responsible for misuse of this software.

About

HTTP Header Security Analyzer

pypi.org/project/argus-header/

Topics

clicybersecuritycybersecurity-toolsheader-analysisheader-analyzerpythontoolsweakness-detectionweakness-reporting

Resources

Readme
MIT license

Contributing

Contributing
Activity

Stars

16 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages