<div align="center">
  <img src=".github/images/logo.svg" alt="MLNops — Monitor, Link, Navigate" width="100%">

  <p><strong>Local-first cyber reconnaissance for MCP clients.</strong></p>
  <p>Monitor the surface. Link the evidence. Navigate the risk.</p>

  [![Python 3.12+](https://img.shields.io/badge/Python-3.12%2B-20D9D2?style=flat-square&logo=python&logoColor=white)](https://www.python.org/)
  [![MCP](https://img.shields.io/badge/Protocol-MCP-8B5CF6?style=flat-square)](https://modelcontextprotocol.io/)
  [![License: MIT](https://img.shields.io/badge/License-MIT-94F7C5?style=flat-square)](LICENSE)
  [![CI](https://github.com/Milindu-Weerawarna/MLNops/actions/workflows/tests.yml/badge.svg)](https://github.com/Milindu-Weerawarna/MLNops/actions/workflows/tests.yml)
  [![MLNops MCP server](https://glama.ai/mcp/servers/Milindu-Weerawarna/MLNops/badges/score.svg)](https://glama.ai/mcp/servers/Milindu-Weerawarna/MLNops)
</div>

---

## What is MLNops?

MLNops is a Python MCP server that equips AI clients with live infrastructure reconnaissance tools. It combines domain registration, DNS, TLS, network, web, email-security, certificate-transparency, and reputation evidence into one structured workflow.

MLNops does not replace professional judgment. It collects evidence and exposes it through MCP; the connected AI client decides which tool to invoke and how to explain the result.

```text
operator request
      │
      ▼
MCP client ──► MLNops tool registry
                   │
         ┌─────────┼─────────┐
         ▼         ▼         ▼
      passive    active    external
      records    probes    intelligence
         └─────────┼─────────┘
                   ▼
          normalized signals
                   ▼
       correlated threat report
```

> MLNops runs locally, but reconnaissance still creates outbound traffic to target systems and third-party services. Use it only on assets you own or are explicitly authorized to assess.

## Capability matrix

### Full reconnaissance pipeline

`full_recon` executes dependency-aware waves and returns raw evidence, tool coverage, normalized signals, and a prompt-ready summary.

| Signal | What MLNops inspects |
|---|---|
| Ownership | WHOIS registration, expiry, registrar, and name servers |
| DNS | A, AAAA, MX, NS, TXT, CNAME, SOA, and common subdomains |
| TLS | Certificate chain, issuer, SANs, cipher, protocol, and expiry |
| Email | SPF, DKIM, DMARC, score, and remediation guidance |
| Network | ASN, BGP prefix, country, registry, and network organization |
| Exposure | Nmap ports, services, and detected versions |
| Web stack | Server, CMS, frameworks, CDN, analytics, and header posture |
| Discovery | Certificate Transparency subdomains with passive-DNS fallback |
| Reputation | AbuseIPDB confidence and malicious-IP indicators |

### Focused tools

| Tool | Purpose |
|---|---|
| `headers_analyzer` | Detailed HTTP security-header analysis |
| `cve_lookup` | NVD CVE search by software and version |
| `cloud_exposure_check` | Checks likely public S3, Azure Blob, and GCS names |
| `trace_redirects` | Maps redirect chains and flags downgrade, loop, and private-IP risks |
| `robots_txt_inspect` | Parses directives, paths, crawl delays, hosts, and sitemaps |

### MCP prompt

`threat_analysis` turns `full_recon` signals into a structured report with:

- an executive security posture;
- confirmed and likely findings separated by severity;
- a transparent 100-point risk score;
- an immediate, weekly, and monthly remediation roadmap;
- explicit insufficient-data handling when a tool is blocked or fails.

## Quick start

### Requirements

- Python 3.12+
- [uv](https://docs.astral.sh/uv/)
- [Nmap](https://nmap.org/download.html) for port scanning
- An MCP-capable client such as Claude Desktop, Cursor, or VS Code

### Install

```bash
git clone https://github.com/Milindu-Weerawarna/MLNops.git
cd MLNops
uv sync --locked
```

Confirm Nmap is available:

```bash
nmap --version
```

### Connect an MCP client

Use absolute paths in your client configuration.

**Windows**

```json
{
  "mcpServers": {
    "MLNops": {
      "command": "C:\\full\\path\\to\\MLNops\\.venv\\Scripts\\python.exe",
      "args": ["C:\\full\\path\\to\\MLNops\\server.py"],
      "env": {
        "ABUSEIPDB_API_KEY": "optional-key"
      }
    }
  }
}
```

**macOS / Linux**

```json
{
  "mcpServers": {
    "MLNops": {
      "command": "/full/path/to/MLNops/.venv/bin/python",
      "args": ["/full/path/to/MLNops/server.py"],
      "env": {
        "ABUSEIPDB_API_KEY": "optional-key"
      }
    }
  }
}
```

`ABUSEIPDB_API_KEY` is optional and used only by `ip_reputation`. All other tools work without it.

Restart the MCP client after changing its configuration, then ask:

```text
What MLNops security tools are available?
```

## Operator examples

```text
Run DNS enumeration on example.com.
Inspect the TLS posture of example.com.
Scan scanme.nmap.org with service detection.
Look up CVEs for Apache 2.4.49.
Trace redirects for https://example.com.
Run a complete authorized recon on my-domain.example.
```

For a correlated report, attach the `threat_analysis` MCP prompt and invoke `full_recon`.

## Port-scan profiles

| Profile | Nmap behavior | Typical use |
|---|---|---|
| `basic` | Fast scan of common ports | Rapid exposure check |
| `service` | Common ports plus version detection | Default full-recon profile |
| `os` | OS detection; elevated privileges may be required | Host characterization |
| `full` | All 65,535 TCP ports | Deep authorized assessment |
| `vuln` | Nmap vulnerability scripts on common ports | Focused validation |

## Architecture

```text
server.py                     MCP entry point and tool registration
tools/                        Reconnaissance implementations
tools/signals/                Evidence normalization and warning extraction
tools/prompts/                Correlation prompt templates
utils/                        Shared validation and parsing helpers
tests/                        Unit and regression tests
mcp.json / server.json        MCP distribution metadata
```

The full-recon scheduler runs tools in waves:

1. Lightweight identity and configuration checks.
2. Active service inspection and passive discovery.
3. Reputation analysis after an IP address has been resolved.

A failed tool is recorded as failed or skipped without terminating the remaining scan.

## Development

```bash
uv sync --locked
uv run pytest tests -q
```

Run the MCP development inspector:

```bash
uv run fastmcp dev inspector server.py
```

See [contributing.md](contributing.md) for tool contracts, signal extraction, testing, and registration guidance.

## Responsible use

- Scan only systems you own or have explicit written permission to test.
- Use `scanme.nmap.org` when learning Nmap against a public target.
- Treat heuristic findings as leads that require validation.
- Do not interpret a missing response as proof of a vulnerability.
- Follow the laws and organizational policies that apply to your environment.



## License and lineage

MLNops is an independent fork and rebuild based on AynOps. It is distributed under the MIT License. The original copyright notice is retained in [LICENSE](LICENSE), and subsequent MLNops modifications are identified there as well.

Maintained by [Milindu Weerawarna](https://github.com/Milindu-Weerawarna).