hats-framework 2.1.0

Professional cybersecurity automation framework with 36 CLI tools and enterprise security

HATS — Hacking Automation Tool Suite

HATS is a lightweight, extensible Python framework that wraps Debian/Kali terminal security tools into tiny, memorable one-line functions so you don't have to memorize noisy CLI flags. Call the tool name as a function — nmap("10.10.10.5"), gobuster("http://target/"), john("<hash>") — and HATS will infer sensible arguments, run the tool, and return parsed, programmatic results.

Scope: CLI/terminal tools only. GUI and menu-driven interactive applications are intentionally out-of-scope.

---

Table of contents

1. Quick highlights
2. Design goals & scope
3. Installation
4. Quick start (examples)
5. Philosophy: one-function-per-tool + automatic inference
6. API reference (surface)
7. Tool configuration (configs/tools.yaml)
8. Output format (what wrappers return)
9. Adding new tools (contributor guide)
10. Integration examples (AI, UI, CI)
11. Roadmap
12. Security & legal disclaimer
13. Tests & CI
14. Contributing & license

---

1. Quick highlights

• One function per tool (function name = tool name): nmap(), gobuster(), john()
• Automatic argument inference: minimal typing, positional args are interpreted (IP, URL, port ranges, wordlist path, hash strings).
• Sane defaults for common tasks (nmap 1-1000, gobuster default wordlist).
• Simple outputs: results returned as JSON-serializable dict with cmd, stdout, stderr, returncode, tool, and interpreted parsed data when available.
• Config-driven: add new CLI tools via configs/tools.yaml (or tools.xml) — no Python code changes needed for simple wrappers.
• Debian-first: HATS is designed to run on Debian-family systems (Kali, Parrot, Ubuntu). It checks for binaries and prints one-line apt install suggestions.
• CLI-only focus: GUI and interactive menu tools are marked interactive: true and excluded from one-line wrappers by default.

---

2. Design goals & scope

Keep HATS minimal and useful:

• Reduce CLI flag memorization and cognitive load.
• Expose a flat, discoverable API (import the function and call it).
• Make outputs program-friendly (easy to parse, store, visualize, or feed to ML/AI).
• Avoid brittle UI automation of GUIs and interactive TUI tools.
• Make it easy for the community to add tool specs (YAML/XML) and parsers.

---

3. Installation

HATS is intended for Debian-based systems only. It deliberately enforces this to avoid dependency and behavior differences across distros.

Prerequisites

• Python 3.7 or higher
• pip package manager

Install Dependencies

pip install -r requirements.txt

Install HATS

# clone & install (dev mode)
git clone https://github.com/your-org/hats.git
cd hats
pip install -e .

# run tests (optional)
python -m pytest tests/

Optional: publish a meta-package hats-kali-bundle (.deb) that installs common pentest tools (nmap, gobuster, sqlmap, john, hydra, etc.). HATS will suggest sudo apt install <tool> when a tool is missing.

---

4. Quick start (examples)

# basic usage
import hats

# 1) simple nmap call (positional target; HATS infers ports + flags)
r = hats.nmap("10.10.10.5")
print(r["cmd"])                 # exact command run
print(r["interpreted"]["open_ports"])   # parsed open ports

# 2) web directory brute force with gobuster
g = hats.gobuster("http://testphp.vulnweb.com")
print(g["interpreted"]["paths_found"][:10])

# 3) john with a raw hash (HATS writes temp file and runs john)
j = hats.john("5f4dcc3b5aa765d61d8327deb882cf99")
print(j["stdout"])

Alternative comprehensive API:

from hats import HATS

# Initialize the engine
engine = HATS()

# Run a single tool with intelligent argument detection
result = engine.nmap("192.168.1.1", range(1, 1000), mode="fast")
print(f"Scan completed: {result['success']}")

# Run async for non-blocking execution
import asyncio
async_result = await engine.nmap_async("scanme.nmap.org")

# Generate reports
report = hats.report(result, format="html", save_to="scan_report.html")

---

5. Philosophy: one-function-per-tool + automatic inference

Positional inference rules (high level)

When you call nmap("10.10.10.5") or gobuster("http://target", "/path/wordlist.txt"), HATS will try to infer fields in this order:

• IP address / CIDR → target
• URL (http/https) → target
• Hostname (contains .) → target
• Port spec (80, 80-443, 1,22,80) → ports
• Existing filepath or name containing wordlist → wordlist
• Hex-like string of length 32/40/64 → hash_input (for john/hash tools)
• Token starting with -/-- → appended to flags
• Fallback: first unknown positional string → target

Advanced control:

• You may pass flags="..." as a keyword argument to pass raw flags to the underlying tool.
• You may pass explicit kwargs (target=..., ports=...) if you want to override inference.

Design goal: common tasks are one-liners; advanced use still supported via flags or explicit kwargs.

---

6. API reference (surface)

This is the public minimal API surface that users of the core wrappers will use.

Example wrapper signatures (flat, positional-first)

• nmap(*positional_args, flags: str = None, **kw) -> dict
• gobuster(*positional_args, flags: str = None, **kw) -> dict
• john(*positional_args, flags: str = None, **kw) -> dict

Return value: a dict with at least:

• tool — tool name (string)
• cmd — exact command executed (string)
• returncode, stdout, stderr — subprocess results
• parsed or interpreted — high-level parsed structure (when parser exists)
• meta — optional metadata used during inference (which args got assigned to what)

All outputs are JSON-serializable.

---

7. Tool configuration (configs/tools.yaml)

HATS loads tool specs from a YAML (or XML) file. Example schema:

tools:
  nmap:
    command: nmap
    category: scanning
    description: "Network discovery and security auditing"
    args: ["-p", "{ports}", "-oX", "-", "{flags}", "{target}"]
    defaults:
      ports: "1-1000"
      flags: "-T4 -sS"
    parser: parse_nmap_xml

  gobuster:
    command: gobuster
    category: web_scanning
    description: "URI/DNS/VHost busting tool"
    args: ["dir", "-u", "{target}", "-w", "{wordlist}", "{flags}"]
    defaults:
      wordlist: "/usr/share/wordlists/dirb/common.txt"
    parser: parse_gobuster

Fields:

• command — binary name executed
• category — tool category for organization
• args — template list; placeholders are filled with inferred fields
• defaults — default values for placeholders
• parser — optional parser function name (must be provided in project parsers)

You can maintain a global ~/.hats/tools.yaml for user customizations and a project configs/tools.yaml.

---

8. Output format (what wrappers return)

Every wrapper returns a dict containing execution metadata and parsed results. Example (nmap):

{
  "tool": "nmap",
  "cmd": "nmap -p 1-1000 -oX - -T4 -sS 10.10.10.5",
  "returncode": 0,
  "stdout": "<nmap xml here>",
  "stderr": "",
  "parsed": {
    "open_ports": [22, 80],
    "services": [
      {"port": 22, "name": "ssh"},
      {"port": 80, "name": "http"}
    ]
  },
  "meta": {
    "inferred": {"target":"10.10.10.5", "ports":"1-1000", "flags":"-T4 -sS"}
  }
}

This makes it trivial to feed results to dashboards, ML models, databases, or REST APIs.

---

9. Adding new tools (contributor guide)

1. Edit configs/tools.yaml (or add your own tools.yaml in ~/.hats/). Add an entry:

   • Add command, category, args (use placeholders), and defaults.

2. If the tool has parsable output that you want structured, add a parser in hats.parsers and set parser: parse_xxx in the spec.

3. Add docs/example usage in examples/.

4. Add unit tests in tests/ (mock subprocess calls where possible).

5. Open a PR.

Because HATS dynamically generates wrapper functions from the specs, no Python code change is needed for simple CLI tools.

---

10. Adding new tools (contributor guide)

1. Edit configs/tools.yaml (or add your own tools.yaml in ~/.hats/). Add an entry:

   • Add command, category, args (use placeholders), and defaults.

2. If the tool has parsable output that you want structured, add a parser in hats.parsers and set parser: parse_xxx in the spec.

3. Add docs/example usage in examples/.

4. Add unit tests in tests/ (mock subprocess calls where possible).

5. Open a PR.

Because HATS dynamically generates wrapper functions from the specs, no Python code change is needed for simple CLI tools.

---

10. Integration examples

• FastAPI: expose HATS as a microservice, e.g. /scan?target=10.10.10.5 runs nmap() and returns JSON.
• Streamlit: create an interactive dashboard that calls gobuster() and displays paths_found.
• CI/CD: run HATS workflows in GitHub Actions to auto-scan staging environments and fail builds on severe findings.
• AI/ML: feed parsed outputs into models (scikit-learn, PyTorch) to prioritize targets or detect anomalies.

---

11. Roadmap

Short-term

• Expand configs/tools.yaml with robust specs for: nmap, masscan, gobuster, nikto, sqlmap, hydra, john, hashcat.
• Add --dry-run/explain() mode to print inferred command without executing.
• Build example Streamlit dashboard and FastAPI wrapper.

Medium-term

• Publish hats-kali-bundle DEB (optional) to simplify first-run setup.
• Provide a small plugin repository of community tool specs.
• Add database backend (SQLite by default) to store scan history.

Long-term

• LLM-assisted workflow orchestrator (AI recommends next tool).
• Plugin marketplace and security sandbox for community specs.

---

12. Security & legal disclaimer

HATS is for authorized security testing, research, and education only. You must have explicit permission to scan or test any network or host. Misuse of HATS may be illegal and could result in civil or criminal liability. The maintainers are not responsible for misuse.

By using HATS you agree to use it ethically and legally.

---

13. Tests & CI

• Unit tests: pytest for parsers and the tool manager (mock subprocess).
• Integration tests: optional, run in a controlled VM/lab (mark as network tests).
• Suggested CI: GitHub Actions to run linting, unit tests, and build wheels.

Run the test suite:

python -m pytest tests/

Or run individual test files:

python -m unittest tests.test_core
python -m unittest tests.test_tool_manager
python -m unittest tests.test_scanning

---

14. Contributing & license

Contributions welcome (>_<):

1. Fork the repo
2. Add your changes on a branch (feature/<name>)
3. Add tests and docs
4. Open a PR

Please follow the project style: keep public API flat, add clear docstrings, and avoid global side-effects.

License: MIT — see LICENSE for full text.