MangScan

MangScan is a lab-oriented port enumeration tool that wraps a two-phase nmap workflow, classifies discovered services, and generates technical reports in JSON and Markdown.

The project is organized as a Python package under src/mangscan, while main.py remains at the repository root as a compatibility entrypoint for local execution.

The repository is also prepared for packaging and release automation through pyproject.toml and GitHub Actions.

Overview

MangScan receives a single target from the command line, performs a full TCP port sweep to identify open ports, and then runs a second, more detailed collection only against those open ports. From the XML generated by nmap, the tool:

• extracts IP, hostname, host status, and exposed services
• identifies versions and basic output from default nmap scripts
• classifies each port into operational categories
• assigns a heuristic priority to findings
• generates simple host profile hypotheses
• exports a structured report for later review

Current Behavior

• CLI input with a single required argument: target
• Phase 1 discovery using -Pn -p- --open -T3
• Phase 2 service enumeration using -Pn -sV -sC -T3 only on open ports found in phase 1
• XML parsing from nmap output into Python objects
• Heuristic classification by category:
  • web
  • remote_access
  • database
  • network_sharing
  • other
• Automatic artifact generation in output/:
  • phase 1 XML
  • phase 2 XML
  • final JSON report
  • final Markdown report

Project Structure

MangScan/
  main.py
  README.md
  requirements.txt
  src/
    mangscan/
      __init__.py
      __main__.py
      cli.py
      config.py
      core/
        models.py
        orchestrator.py
      services/
        classifier.py
        parser.py
        reporter.py
        scanner.py
      utils/
        filesystem.py

Module Responsibilities

• main.py
  • compatibility entrypoint for python main.py <target>
  • injects src/ into sys.path for local execution
• src/mangscan/cli.py
  • CLI parser and terminal output
• src/mangscan/config.py
  • centralized nmap arguments, output directory, and classification rules
• src/mangscan/core/models.py
  • core dataclasses for findings, artifacts, and final result
• src/mangscan/core/orchestrator.py
  • end-to-end execution flow and artifact coordination
• src/mangscan/services/scanner.py
  • python-nmap integration and XML persistence
• src/mangscan/services/parser.py
  • XML parsing into internal models
• src/mangscan/services/classifier.py
  • heuristic categorization, prioritization, and host hypotheses
• src/mangscan/services/reporter.py
  • JSON and Markdown report generation
• src/mangscan/utils/filesystem.py
  • directory creation, timestamping, and port list serialization

Requirements

To run MangScan you need:

• Python 3.10+ recommended
• nmap installed on the system and available in PATH
• permission to scan only authorized environments

Current Python dependency:

python-nmap

Installation

Option 1. Install from PyPI

If the package is already published on PyPI, this is the simplest installation path.

pip install mangscan

If you prefer isolating the installation:

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1
pip install mangscan

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate
pip install mangscan

Option 2. Install from source

1. Clone the repository

git clone <REPOSITORY_URL>
cd MangScan

2. Create and activate a virtual environment

Windows PowerShell:

python -m venv .venv
.venv\Scripts\Activate.ps1

Linux/macOS:

python3 -m venv .venv
source .venv/bin/activate

3. Install Python dependencies

pip install -r requirements.txt

System requirement: install Nmap

MangScan depends on the actual nmap binary. Installing only python-nmap is not enough.

Verify that the command is available:

nmap --version

Usage

If installed from PyPI:

mangscan 192.168.0.10

If running from the repository:

python main.py 192.168.0.10

Verbose runtime logs:

mangscan 192.168.0.10 --log-level DEBUG

You can also run the package directly if src/ is on PYTHONPATH:

python -m mangscan 192.168.0.10

You can also use a hostname:

mangscan lab-host.local

At the end of execution, the CLI prints a short summary with:

• provided target
• identified IP
• open ports list
• total number of open ports

During execution, MangScan now also emits progress logs to the terminal and writes a per-run log file under output/logs/.

By default, output/ is created in the directory where you run the command. You can override this with the environment variable MANGSCAN_OUTPUT_DIR.

Example:

MANGSCAN_OUTPUT_DIR=/tmp/mangscan-output mangscan 192.168.0.10

Generated Output

All artifacts are saved in output/, with names based on timestamp and target.

Examples of generated files:

output/
  20260404_103000_192.168.0.10_phase1.xml
  20260404_103000_192.168.0.10_phase2.xml
  20260404_103000_192.168.0.10_report.json
  20260404_103000_192.168.0.10_report.md
  logs/
    20260404_103000_192.168.0.10.log

The log file records the run lifecycle in more detail, including:

• scan start and end for each phase
• effective nmap arguments
• XML parsing milestones
• classification summary
• report generation paths
• exception stack traces on failure

Execution Flow

1. The user provides an authorized host or IP address.
2. The orchestrator creates a timestamp-based run_id.
3. The tool runs Phase 1 to discover open TCP ports.
4. The Phase 1 XML is parsed to build the list of open ports.
5. If no open ports are found, execution ends with a minimal report.
6. If open ports exist, the tool runs Phase 2 only against those ports.
7. The detailed result is classified and enriched with hypotheses.
8. The final report is written to disk in two formats.

Heuristic Classification

Service classification uses two strategies:

1. Direct mapping based on known ports
2. Inference based on the service name returned by nmap

Currently mapped categories:

• web
• remote_access
• database
• network_sharing
• other

This classification is intentionally simple. It helps organize triage, but it does not replace manual technical analysis.

Limitations

• only one target per execution
• no automated tests yet
• no advanced CLI arguments or external configuration files
• heuristic classification, not validated real-world risk
• no UDP scanning, subnet scanning, or controlled parallelism
• no detailed logging or retry policy
• full dependency on a locally installed nmap

Suggested Roadmap

• add tests for parser, classifier, and reporter
• add CLI flags for scan intensity, ports, output, and formats
• support multiple targets and CIDR ranges
• create an external configuration layer via .env or yaml
• add structured logging
• add HTML and CSV export
• implement historical comparison between executions

Packaging

MangScan is configured as a distributable Python package with a src/ layout and a console entrypoint named mangscan.

Local build commands:

python -m pip install --upgrade build
python -m build

Generated artifacts will be written to:

dist/
  mangscan-0.1.1.tar.gz
  mangscan-0.1.1-py3-none-any.whl

Local editable install:

pip install -e .

GitHub Release And PyPI Publishing

The repository includes a release workflow at .github/workflows/release.yml.

Release flow:

1. Update version in pyproject.toml and __version__ in src/mangscan/__init__.py.
2. Commit the version bump.
3. Create and push a tag matching the version, for example:

git tag v0.1.1
git push origin v0.1.1

When a tag matching v* is pushed, GitHub Actions will:

• validate that the tag matches the package version
• build the source distribution and wheel
• create a GitHub Release with generated notes
• attach the built artifacts to the release
• publish the package to PyPI

PyPI Setup Required Once

Before the automated publishing works, configure the project on PyPI as a Trusted Publisher for this repository.

Recommended values for the PyPI Trusted Publisher form:

• owner: 0xs3n4
• repository: MangScan
• workflow filename: release.yml

If the project does not exist yet on PyPI, create it there first or use PyPI's pending publisher flow.

Ethical and Legal Use

MangScan should only be used:

• in your own labs
• against authorized assets
• in controlled research, defensive, or educational environments

Do not use this tool against third-party assets without explicit authorization. The user is fully responsible for how the tool is used and for any legal or ethical consequences resulting from that use.

License

• GPL-3.0