Metadata-Version: 2.4
Name: argus-header
Version: 0.7.0
Summary: A Python CLI tool for analyzing HTTP response headers and identifying security issues.
Author-email: Sriram <sriram060106@gmail.com>
License: MIT License
        
        Copyright (c) 2025 sriram
        
        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.
        
Project-URL: Homepage, https://github.com/heyshreee/argus-header
Project-URL: Repository, https://github.com/heyshreee/argus-header
Project-URL: Issues, https://github.com/heyshreee/argus-header/issues
Keywords: http,https,headers,security,cybersecurity,cli,pentesting,web-security,header-analysis
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Information Technology
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet :: WWW/HTTP
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests>=2.32.0
Requires-Dist: rich>=13.7.0
Dynamic: license-file

# 🛡️ Argus Header

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

![Python](https://img.shields.io/badge/Python-3.9+-blue.svg)
![Version](https://img.shields.io/badge/version-v0.7.0-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)

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

```bash
pip install argus-header
```

Verify installation:

```bash
argus-header --version
```

Expected output:

```text
Argus Header 0.7.0
```

---

## Install from Source

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

cd argus-header

python -m venv .venv
```

### Windows

```powershell
.venv\Scripts\activate
```

### Linux / macOS

```bash
source .venv/bin/activate
```

Install:

```bash
pip install -e .
```

---

# 🚀 Usage

Basic Scan

```bash
argus-header https://example.com
```

HEAD Request

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

Verbose Report

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

Custom Timeout

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

Multiple URLs

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

Disable Redirects

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

Export JSON

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

Security Score & Grade

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

Export Markdown Report

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

Export HTML Report

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

All Export Formats Together

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

Display Version

```bash
argus-header --version
```

Display Help

```bash
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

```code
$ 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

```text
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:

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

cd argus-header
```

Install the development version:

```bash
python -m venv .venv

# Windows
.venv\Scripts\activate

# Linux / macOS
source .venv/bin/activate

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

Run:

```bash
argus-header https://example.com
```

Run verbose mode:

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

Run the test suite and static checks:

```bash
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.

```bash
git checkout -b feature/my-feature
```

3. Commit your changes.

```bash
git commit -m "feat: add awesome feature"
```

4. Push your branch.

```bash
git push origin feature/my-feature
```

5. 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.
