Pentesting Conventions

Background reference for pentesting workflows. Covers target notation, output formats, safety architecture, scope configuration, lab targets, and project structure.

Target Notation

IP addresses -- Single host (10.0.0.1) or CIDR range (192.168.1.0/24)
Hostnames -- Fully qualified (example.com) or short names
URLs -- Full URL format (http://localhost:8080/path)
Localhost equivalents -- localhost and 127.0.0.1 are interchangeable
Lab targets -- Always use localhost paired to the correct port (see Lab Targets below)

Output Expectations

If wrapper scripts are available (in-repo mode):

Use-case scripts (scripts/<tool>/<use-case>.sh) support two flags:

-j / --json -- Output structured JSON envelope (enables PostToolUse hook summary)
-x / --execute -- Execute commands instead of displaying them

Always add -j when running scripts so Claude receives parsed JSON via the PostToolUse hook. Without -j, Claude gets raw terminal output that is harder to parse.

The examples.sh scripts are learning-mode only and do NOT support -j or -x.

If standalone (plugin mode):

Invoke security tools directly using the command knowledge from your preloaded skills. There are no wrapper scripts -- run tool commands directly and review output manually.

Safety Rules

All commands should be validated against .pentest/scope.json before execution
Check scope before every tool execution
Run security tools responsibly and only against authorized targets
If a scope file does not exist, create one with /netsec-scope init or manually create .pentest/scope.json with {"targets": ["localhost", "127.0.0.1"]}

Scope File

Targets must be listed in .pentest/scope.json before any pentesting commands will execute.

Format:

{"targets": ["localhost", "127.0.0.1"]}

The scope file is gitignored (lives in .pentest/ directory)
Add targets only after confirming authorization to test them
Default safe targets: localhost, 127.0.0.1

Lab Targets

Docker-based vulnerable applications for safe practice:

Service	URL	Credentials
DVWA	http://localhost:8080	admin / password
Juice Shop	http://localhost:3030	(register an account)
WebGoat	http://localhost:8888/WebGoat	(register an account)
VulnerableApp	http://localhost:8180/VulnerableApp	--

If lab infrastructure is available (in-repo mode), manage containers via make targets:

make lab-up -- Start all containers
make lab-down -- Stop all containers
make lab-status -- Show container status

In standalone mode, set up your own vulnerable targets or use existing lab infrastructure.

Project Structure

scripts/<tool>/examples.sh -- Educational examples (10 per tool, learning mode only) [in-repo only]
scripts/<tool>/<use-case>.sh -- Task-focused scripts supporting -j and -x flags [in-repo only]
scripts/common.sh -- Shared utilities (colors, require_cmd, safety_banner, check_cmd) [in-repo only]
scripts/check-tools.sh -- Detects which of 18 pentesting tools are installed [in-repo only]
labs/docker-compose.yml -- Vulnerable Docker targets for practice [in-repo only]
.pentest/scope.json -- Target allowlist (gitignored)
.pentest/audit.log -- Audit log of all tool invocations (gitignored)