Keep Nmap as the source of observations
The scan output remains the technical evidence. AI explanations can help interpret it, but they must not silently replace or rewrite discovered ports and services.
ENGINEERING PROJECT / 02
A Python-based assistant for authorized network assessments, combining Nmap discovery with an interface that helps explain scan results.
01 / CONTEXT
THE WHYRaw scan output can be difficult to interpret, especially when learning network security. The goal was to build a guided workflow that makes the scan scope explicit and turns technical findings into explanations without hiding the underlying evidence.
02 / SYSTEM DESIGN
THE STRUCTUREA high-level view of the documented workflow and component boundaries.
Accepts private IPv4 targets within a bounded assessment scope.
Performs host discovery, TCP port scanning and service-version detection.
Makes discovered hosts, ports and services available to the interface.
Uses the agent workflow to explain observations and estimated risk while preserving scan evidence.
Presents the assessment flow and results for analyst review.
03 / ENGINEERING LOG
THE BUILD SEQUENCEA transparent sequence of engineering milestones. Status labels describe documented work—not a live completion percentage.
Designed the workflow around approved private IPv4 targets, with a documented maximum scope of 256 addresses.
Added host discovery, TCP port scanning and service-version detection as the source of technical observations.
Used a Streamlit interface to present discovered hosts, ports and services while keeping scan evidence available.
Connected the agent workflow to explain observations and potential risk without treating generated explanations as a replacement for scan evidence.
The repository documents pytest and Ruff checks. Use only against systems and networks you own or are explicitly authorized to assess.
04 / DESIGN JUDGMENT
TRADE-OFFS & REASONSThe engineering choices that shape the system—and the reason each boundary exists.
The scan output remains the technical evidence. AI explanations can help interpret it, but they must not silently replace or rewrite discovered ports and services.
An explicit private-address boundary and maximum range make the authorized assessment use case clearer and reduce accidental scope expansion.
A compact interface makes target selection, scan execution and review visible instead of hiding the process behind an opaque agent.
06 / IMPLEMENTATION
THE HOWThe work is broken into practical building blocks, from initial design through to validation.
Accepts user-defined targets within a private IPv4 scope and applies bounded scan limits.
Uses Nmap for host discovery and TCP port and service detection.
Presents scan results through a Streamlit interface.
Uses an AI-assisted workflow to explain discovered services and potential risks while keeping the scan output available for review.
07 / VERIFICATION
THE CHECKSSpecific checks documented for this project. Results are scoped to the recorded lab or test run.
The documented workflow limits discovery to approved private IPv4 ranges of up to 256 addresses.
Host discovery, TCP port scanning and service-version detection provide the underlying observations.
The repository documents pytest and Ruff checks as part of its development workflow.
08 / RESULTS
THE VALUEA practical workflow linking network discovery, structured scan results and natural-language explanations.
A clear interface for reviewing hosts, ports and services.
A project that explores how AI can assist analysis without replacing the original technical evidence.
09 / EVIDENCE
THE BUILDOriginal project captures and walkthrough media. Each item is labelled to explain what it demonstrates.
The video is an existing repository-hosted walkthrough of the application. It is a recorded demonstration, not a live hosted instance; use the README to reproduce the local setup.
Recorded NetSec Agent walkthrough — hosted in the project repository.
10 / ENGINEERING NOTES
TRANSPARENCYClear boundaries matter. These notes describe what the current project does—and what it does not claim to do.