Documentation
Install the sandbox. It will not scan the open internet.
The published copy is the sandbox edition. Before any lookup it checks the target against five approved domains and requires a signed consent receipt. This page documents installation, the command-line surface, the outputs and the boundaries.
1 · Clone and install
Python 3.10 or newer. The package is installed in editable mode so the console entry point becomes available.
2 · List the permitted targets
Read-only. Prints the five approved domains and makes no network request.
3 · Run an assessment
Consent is mandatory. Without the policy flag and a name, the tool refuses.
4 · Verify the consent ledger
Each receipt is chained to the previous one. Verification tells you whether the ledger on this machine is intact.
The allowlist is the product boundary
Any other name — including a look-alike subdomain, a raw IP address, an alternate port or a trailing dot — is rejected before a network request is made. The restriction lives in the runtime, so it cannot be disabled by editing a setting, passing a flag or modifying the interface.
Each name is a reserved documentation domain or a public testing resource published for this purpose:
- example.com / .org / .net — IANA reserved test domains
- scanme.nmap.org — Nmap Project authorised test host
- badssl.com — public TLS and certificate teaching site
Command reference
Every flag the sandbox accepts.
The public CLI is deliberately small. Anything that would widen the target list is absent rather than hidden.
| Flag | Purpose |
|---|---|
--list-domains | Print the five permitted testing domains. Makes no network request. |
--accept-privacy-policy | Record that the privacy policy was read and accepted. Required before any run. |
--consent-user NAME | Operator identity written into the consent receipt. |
--consent-log PATH | Optional path for the consent ledger (default: ~/.smb_scanner_lite/consent_proofs.jsonl). |
--verify-consent-log | Re-walk the SHA-256 hash chain and report whether it is intact. |
--html PATH | Write an HTML report including the consent receipt. |
--json PATH | Write a JSON report for machine processing. |
--txt PATH | Write a plain-text report. |
--gui | Launch the desktop interface for the sandbox. |
--version | Print the application and edition version. |
What you get back
- Score, grade and completed-control count
- One evidence line per conclusive finding
- Inconclusive results listed separately
- Embedded consent receipt, hash-chained
- HTML, JSON or plain text output
Where the ledger lives
Consent receipts are written to the machine that ran the assessment, by default under your home directory. The path is configurable and the file is excluded from Git.
Desktop interface
The same sandbox runtime is available as a GUI for demonstration and teaching. It enforces the identical allowlist and consent requirements.
A blocked target exits with code 2 and a message naming the five permitted domains. A missing policy acceptance or operator name exits with a consent error. Neither case produces a network request — that is the intended behaviour, not a bug to work around.
Need a domain outside the sandbox?
The public edition will not scan it. A private assessment can, after scope and written authorisation are agreed.