nettools-cli 1.0.0

A modern Python network reconnaissance and diagnostics toolkit.

nettools

A modern Python network reconnaissance toolkit.

---

Overview

nettools is a modular Python command-line toolkit for authorized network diagnostics and service discovery. It brings together several common reconnaissance workflows — port scanning, DNS analysis, subdomain enumeration, web inspection, and assessment reporting — into a single, consistent CLI built on top of Typer and Rich.

nettools is intended for:

• Security teams and penetration testers performing authorized assessments
• System administrators auditing infrastructure they manage
• DevOps and network engineers diagnosing connectivity and DNS issues
• Students and researchers learning about network diagnostics in a controlled, ethical context

nettools is not a hacking tool, and it is not designed to bypass authorization, evade detection, or exploit vulnerabilities. It is a diagnostics and reporting utility intended to help authorized users understand the state of systems they are responsible for or have explicit permission to test.

---

Features

• TCP port scanning — Identify open, closed, and filtered TCP ports on target hosts
• DNS lookup — Query common DNS record types (A, AAAA, MX, TXT, NS, CNAME, and more)
• Subdomain enumeration — Discover subdomains using wordlist-based and passive techniques
• Website inspection — Inspect HTTP/HTTPS endpoints, headers, TLS certificate details, and basic metadata
• Unified assessment workflow — Run scan, DNS, subdomain, and web checks together in a single pass
• HTML report generation — Produce clean, shareable HTML reports summarizing findings
• JSON output support — Machine-readable output for every command, suitable for automation and pipelines
• Modular architecture — Each capability lives in its own module, making the codebase easy to extend and maintain

---

Architecture

nettools follows a src-based package layout, keeping the installable package isolated from project tooling and tests.

nettools/
├── src/
│   └── nettools/
│       ├── __init__.py
│       ├── cli.py              # Typer application entry point
│       ├── commands/           # One module per CLI subcommand
│       │   ├── scan.py
│       │   ├── dns.py
│       │   ├── subdomains.py
│       │   ├── web.py
│       │   ├── assess.py
│       │   └── report.py
│       ├── core/               # Shared scanning/analysis logic
│       ├── output/              # Rich console rendering, JSON/HTML formatting
│       └── config.py           # Configuration loading and defaults
├── tests/
│   ├── unit/
│   └── integration/
├── pyproject.toml
├── README.md
├── LICENSE
├── CONTRIBUTING.md
└── SECURITY.md

Each command module is responsible for a single capability and exposes a clear, testable interface. Shared logic (networking primitives, formatting, configuration) lives under core/ and output/ so commands stay thin and consistent.

---

Installation

From PyPI

pip install nettools

From source

git clone https://github.com/your-org/nettools.git
cd nettools
pip install -e .

nettools requires Python 3.13 or later.

---

Usage

View all available commands:

nettools --help

Scan common TCP ports on a target:

nettools scan example.com

Perform DNS lookups:

nettools dns example.com

Run a full assessment (scan, DNS, subdomains, and web inspection together):

nettools assess example.com

Generate an HTML report from previous results:

nettools report

Other available commands:

nettools subdomains example.com
nettools web example.com
nettools version

Most commands support a --json flag for machine-readable output, suitable for scripting or integration with other tools:

nettools scan example.com --json

---

Configuration

nettools can be configured via a project-level configuration file, environment variables, or command-line flags, in increasing order of precedence.

• Configuration file: nettools.toml in the current working directory, or a path passed via --config
• Environment variables: prefixed with nettools_ (e.g. nettools_TIMEOUT, nettools_MAX_WORKERS)
• CLI flags: passed directly to individual commands (e.g. --timeout, --ports, --output)

Common configurable options include:

Option	Description	Default
timeout	Per-connection timeout in seconds	3
max_workers	Concurrent worker threads/processes	50
ports	Port range or list to scan	Common ports (top 1000)
output_dir	Directory for reports and JSON output	./nettools-output
wordlist	Wordlist path for subdomain enumeration	Bundled default wordlist

Refer to nettools <command> --help for the full set of options available on each command.

---

Development Setup

Clone the repository and set up a local development environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

pip install -e ".[dev]"

Run the test suite:

pytest -v

Run linting and type checks:

ruff check .
ruff format .
mypy

---

Testing

nettools uses pytest for automated testing, with unit tests covering individual modules and integration tests covering end-to-end CLI behavior against controlled, local test fixtures. Networking calls in tests are mocked or run against local/loopback targets to keep the suite deterministic and safe to run in CI.

To run the full suite with verbose output:

pytest -v

Contributions are expected to include appropriate test coverage for new functionality. Continuous integration runs the test suite, ruff check, and mypy on every pull request.

---

Roadmap

Planned and potential future improvements include:

• Asynchronous scanning engine for improved performance on large port ranges
• Additional DNS record types and DNSSEC validation checks
• Plugin system for custom assessment modules
• PDF export for assessment reports
• Configurable scan profiles (fast, thorough, stealth-safe timing)
• Expanded passive subdomain enumeration sources
• Structured logging and verbosity controls

Roadmap items are tracked and discussed in the project's GitHub Issues.

---

Contributing

Contributions are welcome. Please read CONTRIBUTING.md for guidelines on:

• Setting up your development environment
• Coding standards and style (enforced via Ruff and Mypy)
• Commit message conventions
• Submitting pull requests and what reviewers look for

---

Security

If you discover a security vulnerability in nettools itself, please do not open a public issue. Instead, follow the responsible disclosure process described in SECURITY.md.

---

License

nettools is released under the MIT License.

---

Responsible Usage

nettools is a diagnostic and reporting tool intended strictly for authorized use.

• Only use nettools against systems, networks, and domains that you own, or for which you have explicit, documented permission to test.
• nettools is intended for authorized diagnostics, auditing, and educational purposes only.
• Unauthorized scanning, enumeration, or assessment of systems you do not own or have permission to test may violate laws and regulations in your jurisdiction, as well as the terms of service of the target system's provider.
• Users are solely responsible for ensuring their use of nettools complies with all applicable laws and any agreements governing the systems being tested.

The maintainers of nettools assume no liability for misuse of this software.