Metadata-Version: 2.4
Name: hackversity
Version: 0.0.3
Summary: A tiered, defensive recon & scanning toolkit for cybersecurity students.
Project-URL: Homepage, https://github.com/hackversity/hackversity-cli
Project-URL: Documentation, https://github.com/hackversity/hackversity-cli#readme
Author: Hackversity
License-Expression: MIT
License-File: LICENSE
Keywords: defensive,education,pentest,recon,scanning,security
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Education
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Security
Requires-Python: >=3.9
Requires-Dist: dnspython>=2.4
Requires-Dist: httpx>=0.27
Requires-Dist: python-whois>=0.9
Requires-Dist: rich>=13.0
Requires-Dist: scapy>=2.5
Requires-Dist: typer>=0.12
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8.0; extra == 'test'
Description-Content-Type: text/markdown

# hackversity

A tiered, **defensive & read-only** recon / scanning toolkit for cybersecurity
students, distributed as a single PyPI package named `hackversity`.

> **Only test systems you own or have explicit written permission to test.**

Every tool is read-only. There is **no** exploit, payload, packet-spoofing, or
injection code anywhere in this package — in any tier. Every scan/probe command
requires an explicit target (there are no default targets and no bundled lists
of real-world hosts) and prints the authorisation notice above before running.

## Install

```bash
pip install hackversity
```

This installs two equivalent console commands: `hackversity` and the short
alias `hv`.

## Command tree

Commands are grouped by verb and tagged by difficulty tier.

| Command | Description | Tier |
| --- | --- | --- |
| `hv scan port <target>` | Threaded TCP connect scan | beginner |
| `hv scan banner <target>` | Grab service banners | beginner |
| `hv scan async <target>` | asyncio connect scan (faster) | intermediate |
| `hv scan hosts <cidr>` | TCP-connect host discovery across a range | intermediate |
| `hv scan version <target>` | Banner-based service/version fingerprinting | intermediate |
| `hv find subdomain <domain>` | DNS brute force + crt.sh | beginner |
| `hv find emails <domain>` | Public-email OSINT (site + WHOIS + crt.sh) | intermediate |
| `hv find urls <domain>` | Historical URLs from the Wayback Machine | intermediate |
| `hv find dirs <url>` | Endpoint discovery (your wordlist) | intermediate |
| `hv find paths <url>` | robots.txt + sitemap.xml advertised paths | intermediate |
| `hv lookup whois <domain>` | WHOIS lookup | beginner |
| `hv lookup dns <domain>` | DNS records + SPF/DMARC/DKIM/CAA | beginner |
| `hv lookup ip <ip>` | Reverse DNS + RDAP + ASN (keyless) | beginner |
| `hv lookup shodan <ip>` | Read an IP's Shodan record (API key) | intermediate |
| `hv analyze headers <url>` | HTTP security-header scoring | intermediate |
| `hv analyze tech <url>` | Web technology fingerprinting | intermediate |
| `hv analyze waf <url>` | Passive WAF / CDN detection | intermediate |
| `hv analyze cors <url>` | CORS misconfiguration checks | intermediate |
| `hv analyze cookies <url>` | Cookie security (Secure/HttpOnly/SameSite) | intermediate |
| `hv analyze tls <host>` | TLS cert / cipher inspection (`--grade` for scoring) | intermediate |
| `hv analyze cve <svc> <ver>` | NVD CVE lookup (informational) | intermediate |
| `hv analyze vulns <scan.json>` | Cross-scan CVE correlation, severity-ranked | advanced |
| `hv analyze takeover <domain>` | Dangling-CNAME subdomain takeover check | intermediate |
| `hv analyze storage <name>` | Public cloud-storage bucket/container check | intermediate |
| `hv analyze pcap <file>` | Summarise a `.pcap` (+ JA3, DNS-tunnel/beacon heuristics) | advanced |
| `hv map topology <target>` | Traceroute + port aggregation | advanced |
| `hv report generate <dir>` | Merge JSON results into a report (Markdown/HTML/**SARIF**) | advanced |
| `hv scope init <file>` | Write a starter scope allowlist | advanced |
| `hv scope check <target>` | Check a target against a scope file | advanced |
| `hv run recon <domain>` | Full recon → enrich → correlate → report pipeline | advanced |

Run `hv --help` or `hv <verb> --help` for full help with examples on every
command.

### Scope enforcement (opt-in)

Point `HACKVERSITY_SCOPE_FILE` at an allowlist (`hv scope init scope.txt`) and
every scan/probe command refuses targets outside it — a guardrail against
accidentally testing something you're not authorised to touch:

```bash
hv scope init scope.txt        # edit it to list your authorised domains/CIDRs
export HACKVERSITY_SCOPE_FILE=scope.txt
hv scan port evil.com          # refused — not in scope.txt
```

With no scope file configured, every target is treated as in scope (unchanged
behaviour) — enforcement is entirely opt-in.

## Use as a Python library

Every tool is importable as a plain function:

```python
from hackversity.tools.beginner import scan_ports, find_subdomains, whois_lookup

results = scan_ports("127.0.0.1", ports=[22, 80, 443])
open_ports = [r.port for r in results if r.is_open]
```

## Development

```bash
pip install -e ".[test]"
pytest
```

## License

MIT
