Build the workflow before adding exploit modules: define scope, produce a plan, validate the actual destinations, execute only approved operations and preserve attributable results. A dry-run flag or an IP allowlist reduces mistakes only when every execution path enforces it.
This is an architecture and acceptance-test guide for a small Python lab toolkit, not a downloadable exploitation framework or a report of a completed pentest. Technical references were checked on October 16, 2026. No scanner or exploit was run for this article.
Make the authorization boundary explicit
Record the approved environment, addresses or hostnames, ports, protocols, actions, time window and emergency contact. Separate permission to observe from permission to send active probes or change state. Active reconnaissance can affect fragile services even when it is not intended to alter data.
Use the assessment planning and rules-of-engagement approach in NIST SP 800-115 as a starting point. A tool cannot determine legal permission from an address. Stop when scope or permitted effects are unclear.
Start with a small controlled lab
Use a local range or a training platform whose rules allow the planned action. Begin with one owned target and one observation module. A VPN connection, private address or publicly downloadable vulnerable VM does not itself establish authorization to test every reachable host.
Keep state-changing modules disabled while developing the shared execution path. A demonstration should use invented data and no customer credentials. A realistic acceptance test verifies refusal behavior as well as a successful authorized run.
Separate observations, actions and conclusions
An observation is an output such as a banner or response. An action may produce a side effect. A conclusion is an interpretation that needs supporting evidence. Store these separately so a matched string cannot silently become a confirmed vulnerability.
Define outcomes such as completed, refused, timed_out, parse_error and unknown. “No finding” is appropriate only when the check completed with enough evidence for that conclusion. A timeout or malformed output is not a clean result.
Give each module one shared contract
The original folder layout is useful: core/ for configuration and validation, checks/ for observation modules, actions/ for separately authorized operations, storage/ for run artifacts and reporting/ for summaries. Keep the execution policy in the shared layer rather than trusting each module to implement a different gate.
A result should identify the run, module and version, requested target, actual destination, start and end times, approved operation, exit status, interpretation status and evidence references. Add a schema version. Reports should consume that contract instead of scraping terminal formatting.
Validate the destination at the execution boundary
Parse addresses with a maintained library such as Python’s ipaddress; address classification is not a permission decision. Match explicit authorized targets and account for IPv4 and IPv6. A private address may belong to an unrelated internal service.
For hostnames and URLs, consider all resolved addresses, redirect destinations and later resolution changes. The OWASP SSRF prevention guidance explains why parsing and one-time DNS checks are insufficient. Refuse ambiguous or unapproved destinations. If a wrapper cannot enforce destination policy for the tool it launches, do not claim it provides that protection.
A dry-run should show the planned target, operation and output location and perform no target-facing action. If resolving DNS is part of planning, disclose that network activity; it is not a completely offline dry-run. Revalidate immediately before execution and use lab network controls as an additional boundary.
Wrap external tools without introducing another interpreter
Choose a library when its supported API gives the required control; choose a subprocess wrapper when the external tool has a stable output format and suitable destination controls. Both need version tracking, error handling and bounded resource use.
The Python subprocess documentation supports passing an argument sequence without a shell. Avoid constructing a shell command from target text. This prevents shell interpretation but does not prevent option injection into the launched program: validate values and use its end-of-options convention where supported.
Set execution limits and capture exit status separately from parsed findings. Large captured outputs can consume memory. Timeout behavior and subprocess cleanup need explicit design, including descendants; terminating a local process does not undo an action the target already received.
Preserve raw output and test the parser
Keep restricted raw evidence separate from the concise result, with a path or identifier linking them. Normalize timestamps and identity fields while retaining the original values needed to investigate a disagreement. Parsing should not discard an error because a familiar success phrase was also present.
Use synthetic fixtures for successful output, empty output, nonzero exits, unexpected formats and partial results. A tool update should trigger parser review. Compare the schema and interpretation, not an expectation that a live service always produces identical bytes.
Minimize secrets in every artifact
Use run and module identifiers to connect events. Record operation names and approved options, but remove credentials from command lines, logs and screenshots. Debug output, environment variables, URLs and exceptions can also expose secrets. Redaction is a reviewable process, not a guarantee provided by a filename.
Keep restricted raw artifacts only when necessary and permitted; publish a redacted report view. Hashing an artifact can help detect changes relative to the recorded digest, but does not prove the original interpretation or authorize sharing. Define access and retention before collection.
Bound retries and represent uncertain outcomes
Retry only operations whose repeated effects are understood and authorized, with a limited attempt count and delay policy. A failed connection, authentication failure, scope refusal and parser failure need different responses. Do not automatically broaden the target or lower a protection to make a check pass.
If a state-changing request times out, its effect may be unknown. Record that uncertainty and inspect the target through an approved method instead of submitting it again automatically. A concurrency setting limits simultaneous workers; it does not by itself set a safe request rate or predict total runtime.
Acceptance checks before adding capability
Confirm that an empty allowlist refuses execution; an out-of-scope address is refused; alternate IPv6 and redirect paths follow the same policy; and a dry-run does not invoke a target-facing module. Test malformed configuration and output-directory failures. Verify these against the actual execution path, not only a validation helper.
Then test an authorized synthetic fixture, a parser failure, a timeout and a cancellation. Confirm that no result is silently labeled clean and no action is retried without policy. Review the artifacts for secrets. These are proposed acceptance criteria, not tests reported as passed by an implementation supplied here.
Common questions
Is a private-IP-only default enough? No. It can reduce accidental exposure but is not an authorization boundary. Use explicit scope and enforce the destination policy for each supported operation.
Should recon automatically trigger an exploit? Keep that as a separate, explicitly permitted operation with reviewed preconditions and effects. A detected version or signature is not sufficient proof that an exploit is appropriate.
Next step: one plan and one result fixture
Draft the scope model, shared result schema and one synthetic parser fixture. Add a plan-only command, then review how the chosen module enforces destination and retry policy. The essential Kali workflows guide can help choose a narrowly defined first module.
Keep the project’s claims proportional to the implementation: a skeleton with a parser is not yet a tested safe execution engine. Document unsupported paths before expanding the toolkit.
Build evidence and refusal behavior together
A useful toolkit makes authorized work reproducible and failures visible. Preserve the small architecture, validate the real execution boundary and verify the result model before adding more actions. That gives the next module a clear contract instead of another unreviewed shortcut.