htb-init

htb-init is a Bash-based Hack The Box workspace initializer, first-stage recon automation helper, recon archiver, and recon-analysis workflow.

It creates a clean workspace for a new HTB machine, generates target configuration, helper scripts, starter notes, a writeup template, a Linux privilege escalation checklist, automated recon tooling, and a ZIP archive helper.

The repository also includes analyze-recon.py, a standalone recon analysis helper that reviews collected recon output and generates prioritized next-step suggestions. It works offline by default and can optionally enrich findings with online vulnerability intelligence from OSV and NVD.

The workflow is intended for authorized Hack The Box labs.

---

Features

• Creates a structured workspace under /home/zendeni/htb_labs/<box>/
• Generates a machine-local .target.env
• Generates an /etc/hosts update helper
• Generates an automated recon.sh script
• Generates a recon ZIP archive helper
• Generates starter notes.md and writeup.md
• Generates a Linux privilege escalation checklist
• Runs service-aware enumeration based on discovered ports
• Performs TCP and UDP discovery
• Performs web discovery with ProjectDiscovery httpx when available
• Falls back to curl-based HTTP/HTTPS probing when ProjectDiscovery httpx is unavailable
• Uses faster timeout-safe curl probing for Windows/AD-style targets
• Avoids wasting time on obvious non-web AD ports during web probing
• Runs service-specific enumeration for DNS, SMB, FTP, SSH, NFS/RPC, SNMP, LDAP, Kerberos, and WinRM
• Wraps noisy/hanging SMB tools such as enum4linux with a timeout
• Saves console output and recon summaries
• Automatically creates a ZIP archive after recon
• Avoids overwriting existing notes.md and writeup.md
• Provides optional recon interpretation through analyze-recon.py
• Supports optional online vulnerability intelligence lookup through OSV and NVD
• Supports optional NVD API key usage
• Supports analysis of both live workspace folders and archived recon ZIP files

---

Repository Structure

htb-init/
├── README.md
├── htb-init.sh
└── analyze-recon.py

---

Installation

Clone the repository:

git clone https://github.com/Zendeni/htb-init.git
cd htb-init

Make the scripts executable:

chmod +x htb-init.sh
chmod +x analyze-recon.py

Install htb-init as a system command:

sudo cp htb-init.sh /usr/local/bin/htb-init
sudo chmod +x /usr/local/bin/htb-init

Optional: install analyze-recon.py into your HTB tools folder:

mkdir -p /home/zendeni/tools/htb
cp analyze-recon.py /home/zendeni/tools/htb/analyze-recon.py
chmod +x /home/zendeni/tools/htb/analyze-recon.py

Confirm installation:

which htb-init
head -n 1 "$(which htb-init)"
bash -n "$(which htb-init)" && echo "syntax OK"

Expected:

/usr/local/bin/htb-init
#!/usr/bin/env bash
syntax OK

Confirm the analyzer:

/home/zendeni/tools/htb/analyze-recon.py -h

---

Usage

htb-init <box-name> <target-ip>

Example:

htb-init principal 10.129.244.220

Use the short box name only. Do not include .htb.

Correct:

htb-init principal 10.129.244.220

Wrong:

htb-init principal.htb 10.129.244.220

This creates:

/home/zendeni/htb_labs/principal

and configures:

BOX="principal"
IP="10.129.244.220"
HOST="principal.htb"
BASE_DIR="/home/zendeni/htb_labs/principal"

---

Requirements

The script expects a Linux/Kali-style environment.

Required:

bash
sudo
awk
getent
nmap
timeout
zip
python3

Strongly recommended:

curl
whatweb
feroxbuster
ffuf
nikto
dig
dnsrecon
gobuster
smbclient
enum4linux-ng
enum4linux
smbmap
showmount
rpcinfo
snmpwalk
onesixtyone
ldapsearch
jq
nc
openssl
ftp

Optional but useful:

httpx
nuclei
netexec
crackmapexec

Optional for online vulnerability intelligence:

Internet access
NVD API key

Notes:

• If ProjectDiscovery httpx is available, recon.sh uses it for HTTP/HTTPS probing.
• If another tool named httpx is installed, recon.sh detects this and falls back to curl.
• If httpx is missing entirely, recon.sh also falls back to curl.
• enum4linux and enum4linux-ng are useful but can be noisy or slow on Windows/AD targets, so they are timeout-wrapped.
• analyze-recon.py uses only the Python standard library.
• Online vulnerability lookup is optional and must be explicitly enabled.

---

What It Creates

/home/zendeni/htb_labs/<box>/
├── .target.env
├── update-hosts.sh
├── recon.sh
├── zip-recon.sh
├── privesc-linux.md
├── notes.md
├── writeup.md
├── README.md
├── scans/
├── enum/
│   ├── web/
│   ├── dns/
│   ├── smb/
│   ├── ftp/
│   ├── nfs/
│   ├── snmp/
│   ├── ldap/
│   ├── kerberos/
│   ├── rpc/
│   ├── winrm/
│   ├── ssh/
│   └── other/
├── loot/
├── exploits/
├── shells/
├── screenshots/
└── tools/

After recon.sh runs, it also creates:

summary.md
recon-console.log
<box>-recon-<timestamp>.zip

If analyze-recon.py is run against the workspace, it creates:

recon-analysis.md

---

Main Generated Files

.target.env

Stores machine-specific variables used by the helper scripts:

BOX="principal"
IP="10.129.244.220"
HOST="principal.htb"
BASE_DIR="/home/zendeni/htb_labs/principal"

The generated helper scripts source this file, which makes them location-aware and reusable.

---

update-hosts.sh

Safely updates /etc/hosts for the current target.

Run it from inside the box folder:

./update-hosts.sh

It removes old entries for the same hostname and adds the current one:

10.129.244.220 principal.htb

The script avoids unsafe regex-based deletion and updates only entries where the hostname matches as a field.

---

recon.sh

Runs automated first-stage recon against the target.

Run:

./recon.sh

It performs:

- Tool availability check
- Full TCP port scan
- TCP service/version enumeration
- TCP aggressive scan
- TCP default/safe Nmap scripts
- UDP top ports scan
- HTTP/HTTPS discovery
- Web enumeration with whatweb, curl, feroxbuster, ffuf, nikto
- Host-header web checks
- JavaScript extraction and keyword grep
- DNS enumeration if port 53 is open
- SMB enumeration if ports 139/445 are open
- FTP enumeration if port 21 is open
- SSH enumeration if port 22 is open
- NFS/RPC enumeration if relevant ports are open
- SNMP enumeration if UDP/161 is found
- LDAP enumeration if LDAP ports are open
- Kerberos enumeration if port 88 is open
- WinRM enumeration if ports 5985/5986 are open
- Optional Nmap vulnerability script scan
- Interesting keyword grep
- Recon summary generation
- Automatic ZIP archive generation

Important generated outputs:

summary.md
recon-console.log
scans/tcp-full.txt
scans/tcp-services.txt
scans/tcp-aggressive.txt
scans/tcp-default-safe-scripts.txt
scans/tcp-vuln.txt
scans/udp-top100.txt
scans/port-summary.md
enum/web/live-web-urls.txt
enum/web/curl-web-probe.txt
enum/interesting-grep.txt

---

zip-recon.sh

Creates a ZIP archive of recon material.

Run manually with:

./zip-recon.sh

recon.sh also runs it automatically at the end.

The archive includes:

.target.env
scans/
enum/
notes.md
writeup.md
README.md
recon.sh
update-hosts.sh
zip-recon.sh
privesc-linux.md
summary.md
recon-console.log

It excludes bulky or sensitive folders/files:

loot/
exploits/
shells/
screenshots/
*.pcap
*.cap
*.zip

---

notes.md

Working notes for:

- Target info
- Open ports
- Credentials
- Interesting findings
- Attack ideas
- Foothold
- Privilege escalation
- Loot
- Proofs

If notes.md already exists, htb-init leaves it unchanged.

---

writeup.md

Starter writeup template with sections for:

- Enumeration
- Initial access
- Local enumeration
- Privilege escalation
- Attack chain summary
- MITRE ATT&CK mapping
- Remediation summary

If writeup.md already exists, htb-init leaves it unchanged.

---

privesc-linux.md

Linux privilege escalation checklist covering:

- Current user/context
- sudo permissions
- Users and groups
- SUID/SGID binaries
- Capabilities
- Writable paths
- Processes/services
- Cron jobs
- Interesting files
- Shell stabilization

---

analyze-recon.py

analyze-recon.py is a standalone recon analysis helper.

It does not run exploitation. It does not modify the target. It reads collected recon output and generates a prioritized analysis report.

It supports:

- Extracted HTB workspace folders
- ZIP archives generated by zip-recon.sh
- Offline analysis by default
- Optional online vulnerability intelligence lookup

Example against a workspace folder:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal

Example against a recon ZIP:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal/principal-recon-20260524-135821.zip

Example with terminal output:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal --print

It generates:

recon-analysis.md

Depending on the available data, it attempts to extract and summarize:

- Target metadata
- Open ports
- Detected services
- Detected technologies
- Likely machine profile
- Web URLs
- Web headers
- Forms and input fields
- JavaScript references
- API endpoints
- Authentication-related clues
- SMB shares
- LDAP naming contexts
- AD/DC indicators
- MSSQL indicators
- WinRM indicators
- Detected packages/components
- Top vulnerability candidates
- Vulnerability intelligence
- Vulnerability references
- High-value next steps
- CVE/research search suggestions
- Interesting grep highlights

Example output sections:

Detected Profile
Open Ports
Detected Technologies
Web Intelligence
Detected Packages / Components
Top Vulnerability Candidates
Vulnerability Intelligence
Vulnerability References
Prioritized Findings and Next Steps
CVE / Research Search Suggestions
Interesting Grep Highlights
Files Parsed

Treat all suggestions from analyze-recon.py as hypotheses requiring manual validation.

---

Online Vulnerability Intelligence

By default, analyze-recon.py runs offline.

To enable OSV and NVD lookup:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal --online-vuln-check

This enriches the report with:

- OSV package/version matches
- NVD keyword/CVE matches
- Top vulnerability candidates
- Severity
- Relevance score
- Advisory references

Example:

cd /home/zendeni/htb_labs/reactor

/home/zendeni/tools/htb/analyze-recon.py . --online-vuln-check

Example output summary:

[+] Recon root: /home/zendeni/htb_labs/reactor
[+] Parsed files: 63
[+] Open ports parsed: 2
[+] Findings generated: 6
[+] Packages/components detected: 3
[+] Vulnerability matches: 40
[+] Wrote analysis: /home/zendeni/htb_labs/reactor/recon-analysis.md

The report can identify exact package/version matches, such as:

npm:next 15.0.3
npm:react 19.0.0-rc
npm:react-server-dom-webpack

And it can rank relevant findings, such as:

GHSA-9qr9-h5gf-34mp / CVE-2025-55182
Authorization Bypass in Next.js Middleware
React Server Components issues
Next.js Server Actions issues

NVD API Key

NVD can be queried without an API key, but an API key is recommended to reduce rate-limit problems.

Set it as an environment variable:

export NVD_API_KEY='your-api-key-here'

Then run:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal --online-vuln-check

Or pass it directly:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal   --online-vuln-check   --nvd-api-key 'your-api-key-here'

Vulnerability Cache

The analyzer can cache vulnerability lookup results.

Use a custom cache path:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal   --online-vuln-check   --vuln-cache ~/.cache/htb-recon/vuln-cache.json

Recommended pattern:

mkdir -p ~/.cache/htb-recon

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal   --online-vuln-check   --vuln-cache ~/.cache/htb-recon/vuln-cache.json

Offline vs Online Mode

Offline mode is best for fast, repeatable analysis:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal

Online mode is best when you want current vulnerability intelligence:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/principal --online-vuln-check

The online results are useful, but still require manual validation. Exact OSV package/version matches are usually stronger than broad NVD keyword matches.

---

Recommended Workflow

1. Initialize the box

htb-init principal 10.129.244.220

2. Enter the workspace

cd /home/zendeni/htb_labs/principal

3. Update /etc/hosts

./update-hosts.sh

4. Run recon

./recon.sh

5. Review the raw recon summary

less summary.md

6. Run offline recon analysis

/home/zendeni/tools/htb/analyze-recon.py .

Review:

less recon-analysis.md

7. Run online vulnerability-enriched analysis

/home/zendeni/tools/htb/analyze-recon.py . --online-vuln-check

Review:

less recon-analysis.md

8. Archive recon

Usually this is already done automatically by recon.sh, but it can also be run manually:

./zip-recon.sh

---

Useful Review Commands

cat scans/open-tcp-ports.txt
cat scans/port-summary.md
cat enum/web/live-web-urls.txt
cat enum/web/curl-web-probe.txt
cat enum/interesting-grep.txt
less summary.md
less recon-analysis.md

For Windows/AD-style boxes:

cat enum/smb/smbclient-null.txt 2>/dev/null
cat enum/smb/netexec-smb.txt 2>/dev/null
cat enum/ldap/namingcontexts.txt 2>/dev/null
cat enum/winrm/netexec-winrm.txt 2>/dev/null
cat scans/port-summary.md

For web-heavy boxes:

cat enum/web/live-web-urls.txt
grep -RniE "fetch|axios|/api/|token|auth|login|admin|dashboard|password|secret" enum/web/
find enum/web -type f -size +0c | sort

For vulnerability-enriched reports:

grep -n "Top Vulnerability Candidates" -A20 recon-analysis.md
grep -n "Vulnerability Intelligence" -A40 recon-analysis.md
grep -n "Prioritized Findings" -A80 recon-analysis.md

---

Safety and Validation

htb-init validates:

- Box name format
- Short box name only, not box.htb
- IPv4 address format
- IPv4 octets between 0 and 255

It does not overwrite existing:

notes.md
writeup.md

This prevents accidental loss of manual notes or report work when rerunning htb-init.

The recon workflow is intended for authorized lab targets only.

analyze-recon.py does not exploit targets. It only reads local recon output and optionally queries public vulnerability databases for enrichment.

---

Example

htb-init bounty 10.129.37.20
cd /home/zendeni/htb_labs/bounty
./update-hosts.sh
./recon.sh
less summary.md

Result:

/home/zendeni/htb_labs/bounty/

with:

bounty.htb
10.129.37.20

and a generated archive like:

bounty-recon-20260524-153000.zip

Optional offline analysis:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/bounty
less /home/zendeni/htb_labs/bounty/recon-analysis.md

Optional online vulnerability-enriched analysis:

/home/zendeni/tools/htb/analyze-recon.py /home/zendeni/htb_labs/bounty --online-vuln-check
less /home/zendeni/htb_labs/bounty/recon-analysis.md

---

Notes

This tool is designed for personal HTB methodology, repeatability, and clean writeup preparation.

It does not perform exploitation. It creates a workspace, runs first-stage enumeration, packages recon data, and optionally analyzes collected recon artifacts for likely next steps and vulnerability intelligence.

Keep htb-init.sh stable. Develop and improve analyze-recon.py separately so recon collection remains reliable.