🪡 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

git clone https://github.com/H4CK-7H3-P14N37/needlecraft.git
cd needlecraft

2. Install the Python package

pip install .

3. Install system dependencies

Installs apt packages and deploys torrc. Requires root.

exercism install-deps

Tor is not started automatically. When you need it:

systemctl start tor

Configuration

Set API keys and credentials. Written to ~/.config/exercism.json and /etc/environment.

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:

exercism config --show

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

Usage

Port scan

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)

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

exercism sslscan urls.txt

Screenshots

exercism screenshot urls.txt

Passive DNS

exercism pdns ips.txt
exercism pdns ips.txt -o output.txt

InternetDB lookup

exercism internetdb ips.txt

Dehashed credential search

exercism dehashed example.com
exercism dehashed user@example.com -s 500

Recon (WHOIS / subdomain enumeration)

exercism recon example.com

MaxMind ASN lookup

exercism maxmind -k "Company Name"
exercism maxmind -k "Company Name" -s output.json

Mass DNS lookup

exercism dns domains.txt

Tor site screenshot

exercism tor http://example.onion

Ansible → OpenSSH config

exercism ansible inventory.ini ~/.ssh/config
exercism ansible inventory.ini ~/.ssh/config -g group1,group2

Generate attack surface report

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:

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.