This article covers the design principles that differentiate well-engineered security tools from quick scripts — applicable whether you are building your first Python security tool or evaluating open source tooling for enterprise use.
The most important decision in security tool development is not technical — it is the frame you build around the tool.
A network scanner and a port scanner are the same code. The difference is:
A tool that requires the user to bypass its own safeguards to misuse it is a better-designed tool than one that requires no configuration at all.
This framing matters for three reasons: legal risk, professional credibility, and visa portfolio integrity. Every tool you publish is evidence in your professional narrative.
A professional Python security tool follows a clear structure:
tool-name/
├── README.md # Installation, usage, authorisation notice
├── requirements.txt # Pinned dependencies
├── setup.py # Package installation
├── LICENSE # MIT (or chosen licence)
├── tool_name/
│ ├── __init__.py
│ ├── cli.py # Command-line interface (argparse or Click)
│ ├── core.py # Core logic — scan, analyse, collect
│ ├── output.py # Report formatting — JSON, CSV, HTML
│ └── utils.py # Shared utilities
└── tests/
├── test_core.py
└── test_output.py
This structure is immediately recognisable to any security engineer evaluating your tool — it signals professionalism before a single line of core logic is read.
import argparse
import sys
def build_parser():
parser = argparse.ArgumentParser(
description='Network Scanner — for authorised security assessments only',
formatter_class=argparse.RawDescriptionHelpFormatter,
epilog="""
AUTHORISATION NOTICE:
This tool must only be used against systems you own
or have explicit written permission to test.
Unauthorised use is illegal and unethical.
Examples:
python scanner.py --target 192.168.1.0/24 --ports 22,80,443
python scanner.py --target 10.0.0.1 --ports 1-1024 --output json
"""
)
parser.add_argument('--target', required=True, help='Target IP or CIDR range')
parser.add_argument('--ports', default='1-1024', help='Port range (e.g., 22,80,443 or 1-1024)')
parser.add_argument('--output', choices=['json', 'csv', 'html'], default='json')
parser.add_argument('--timeout', type=float, default=1.0, help='Connection timeout in seconds')
parser.add_argument('--threads', type=int, default=50, help='Maximum concurrent threads')
return parser
def main():
parser = build_parser()
args = parser.parse_args()
# Authorisation prompt — built in by default
print(f"\n[!] Target: {args.target}")
confirm = input("[!] Confirm you have authorisation to scan this target [y/N]: ")
if confirm.lower() != 'y':
print("[-] Scan cancelled.")
sys.exit(0)
# Proceed with scan
run_scan(args)
The authorisation prompt is non-negotiable. It adds two seconds to the workflow and provides significant legal protection while communicating responsible design intent to anyone reviewing the code.
Security tools frequently benefit from concurrent execution — scanning 1,000 ports sequentially is slow; scanning them with 50 concurrent threads is practical.
import socket
import threading
from queue import Queue
from dataclasses import dataclass
from typing import List
@dataclass
class ScanResult:
port: int
state: str
service: str = ''
def scan_port(target: str, port: int, timeout: float) -> ScanResult:
"""Attempt TCP connection to target:port."""
try:
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.settimeout(timeout)
result = sock.connect_ex((target, port))
sock.close()
if result == 0:
# Attempt service banner grab
service = get_service_banner(target, port, timeout)
return ScanResult(port=port, state='open', service=service)
except (socket.timeout, socket.error):
pass
return ScanResult(port=port, state='closed')
def threaded_scan(target: str, ports: List[int],
timeout: float, max_threads: int) -> List[ScanResult]:
"""Thread pool scan across port list."""
results = []
results_lock = threading.Lock()
queue = Queue()
for port in ports:
queue.put(port)
def worker():
while not queue.empty():
try:
port = queue.get_nowait()
result = scan_port(target, port, timeout)
if result.state == 'open':
with results_lock:
results.append(result)
queue.task_done()
except Exception:
queue.task_done()
threads = []
for _ in range(min(max_threads, len(ports))):
thread = threading.Thread(target=worker, daemon=True)
thread.start()
threads.append(thread)
for thread in threads:
thread.join()
return sorted(results, key=lambda r: r.port)
Professional security tools produce output that can be consumed by other tools, imported into reports, and reviewed by non-technical stakeholders.
import json
import csv
from datetime import datetime
from typing import List
def export_json(results: List[ScanResult], target: str, output_path: str):
"""Export scan results as structured JSON."""
report = {
"metadata": {
"tool": "network-scanner",
"version": "1.0.0",
"target": target,
"timestamp": datetime.utcnow().isoformat() + "Z",
"authorisation": "Confirmed by operator"
},
"summary": {
"open_ports": len(results),
"ports_scanned": "see configuration"
},
"findings": [
{
"port": r.port,
"state": r.state,
"service": r.service
}
for r in results
]
}
with open(output_path, 'w') as f:
json.dump(report, f, indent=2)
print(f"[+] Report saved: {output_path}")
JSON output is the minimum standard. A tool that only prints to stdout is a script; a tool that produces structured, versioned, metadata-rich output is a professional product.
A README that a CISO could hand to their legal team is a README that gets your tool taken seriously:
# tool-name
One sentence description.
**For authorised security assessments only.**
## Installation
pip install tool-name
## Usage
python -m tool_name --target 192.168.1.1 --ports 1-1024
## Authorisation
This tool must only be used against systems you own or have
explicit written authorisation to test. The operator is solely
responsible for ensuring legal compliance in their jurisdiction.
## Licence
MIT — see LICENSE
Python is appropriate for most security tooling. Rust becomes relevant for:
The learning curve is significant but the output quality difference is measurable. DFIR triage collectors handling evidence must not corrupt data — a Rust implementation with compile-time memory safety guarantees is materially more trustworthy than Python in that context.
Security tool development is applied security research — every tool teaches you something about the systems it tests or defends. The design principles that make a tool professionally credible (structured output, authorisation prompts, clear documentation, responsible framing) are the same principles that make it genuinely useful in enterprise environments.
The next article covers building the AD Enumerator — the first tool in this series, with full implementation walkthrough.
Questions or contributions? Get in touch.
]]>