Metadata-Version: 2.4
Name: needlecraft
Version: 1.0.2
Summary: External attack surface recon toolkit for red team engagements: port/SSL scanning, passive DNS, OSINT search (Shodan, InternetDB, Dehashed, MaxMind), screenshotting, and attack surface report generation.
Requires-Python: >=3.13
Description-Content-Type: text/markdown
Requires-Dist: dnspython
Requires-Dist: lxml
Requires-Dist: netaddr
Requires-Dist: pandas
Requires-Dist: requests
Requires-Dist: requests-file
Requires-Dist: shodan
Requires-Dist: tldextract
Requires-Dist: validators
Requires-Dist: xlrd
Requires-Dist: XlsxWriter
Requires-Dist: xmltodict
Requires-Dist: python-docx
Requires-Dist: Pillow
Requires-Dist: imagehash
Requires-Dist: scikit-learn
Requires-Dist: numpy
Requires-Dist: jinja2

# 🪡 Needlecraft

**External attack surface recon toolkit for red teamers.** One CLI to scan, search, screenshot, and report — from first port sweep to finished deliverable.

Needlecraft ships two commands:

- **`exercism`** — recon and scanning: ports, SSL/TLS, DNS, OSINT, screenshots, Tor.
- **`salvare`** — turns raw findings into a polished attack surface report.

## Why Needlecraft

- 🎯 **One tool, whole workflow** — stop stitching together nmap, masscan, sslscan, EyeWitness, and a dozen OSINT APIs by hand.
- 🔍 **OSINT built in** — Shodan, InternetDB, Dehashed, MaxMind, and WHOIS/subdomain recon out of the box.
- 🧅 **Tor-aware** — screenshot `.onion` sites without extra plumbing.
- 📄 **Report generation** — `salvare` compiles ports, ciphers, certs, and screenshots into a client-ready `.docx`.

## Installation

### 1. Clone the repository
```bash
git clone https://github.com/H4CK-7H3-P14N37/needlecraft.git
cd needlecraft
```

### 2. Install the Python package
```bash
pip install .
```

### 3. Install system dependencies
Installs apt packages and deploys `torrc`. Requires root.
```bash
exercism install-deps
```
Tor is not started automatically. When you need it:
```bash
systemctl start tor
```

## Configuration

Set API keys and credentials. Written to `~/.config/exercism.json` and `/etc/environment`.
```bash
exercism config SHODANKEY=your_key HIBPKEY=your_key SECURITYTRAILSKEY=your_key
exercism config GOOGLEKEY=your_key GOOGLECX=your_cx
exercism config MAXMINDKEY=your_key
exercism config DEHASHED_EMAIL=you@example.com DEHASHED_API_KEY=your_key
exercism config GMAIL_EMAIL=you@example.com GMAIL_APP_PASSWORD=your_password
```

Show current config:
```bash
exercism config --show
```

See `env.example` for the full list of supported keys.

## Usage

### Port scan
```bash
exercism scan ips_list.txt
exercism scan ips_list.txt -u -l -p -t
exercism scan ips_list.txt -T          # top 100 TCP ports only
exercism scan ips_list.txt -N          # skip nmap, masscan results only
exercism scan ips_list.txt -e you@example.com  # email results when done
```

### Search (IP, domain, email, CVE)
```bash
exercism search 1.1.1.1
exercism search example.com
exercism search CVE-2024-1234
exercism search user@example.com
exercism search 1.1.1.1 -s   # short output
```

### SSL scan
```bash
exercism sslscan urls.txt
```

### Screenshots
```bash
exercism screenshot urls.txt
```

### Passive DNS
```bash
exercism pdns ips.txt
exercism pdns ips.txt -o output.txt
```

### InternetDB lookup
```bash
exercism internetdb ips.txt
```

### Dehashed credential search
```bash
exercism dehashed example.com
exercism dehashed user@example.com -s 500
```

### Recon (WHOIS / subdomain enumeration)
```bash
exercism recon example.com
```

### MaxMind ASN lookup
```bash
exercism maxmind -k "Company Name"
exercism maxmind -k "Company Name" -s output.json
```

### Mass DNS lookup
```bash
exercism dns domains.txt
```

### Tor site screenshot
```bash
exercism tor http://example.onion
```

### Ansible → OpenSSH config
```bash
exercism ansible inventory.ini ~/.ssh/config
exercism ansible inventory.ini ~/.ssh/config -g group1,group2
```

### Generate attack surface report
```bash
salvare genreport \
  reports/attack_surface_ports.csv \
  reports/attack_surface_ciphers.csv \
  reports/attack_surface_certs.csv \
  reports/screenshots/ \
  "Company Name" \
  scope.txt
```

## Development install

For making changes without reinstalling:
```bash
pip install -e .
```

## Disclaimer

Needlecraft is built for authorized security testing. Only point it at assets you own or have explicit written permission to assess.
