from __future__ import annotations
import os
import json
from typing import Any, Dict, List, Optional
from urllib.parse import urljoin
import requests
from requests.auth import HTTPBasicAuth
from fastmcp import FastMCP
# -----------------------------------------------------------------------------
# Configuration
# -----------------------------------------------------------------------------
IP360_BASE_URL = os.getenv("IP360_BASE_URL", "https://127.0.0.1/rest/v1/")
IP360_USERNAME = os.getenv("IP360_USERNAME", "")
IP360_PASSWORD = os.getenv("IP360_PASSWORD", "")
IP360_VERIFY_TLS = os.getenv("IP360_VERIFY_TLS", "true").lower() in ("1", "true", "yes")
IP360_TIMEOUT = int(os.getenv("IP360_TIMEOUT", "30"))
mcp = FastMCP(
"Tripwire IP360 MCP",
instructions=(
"Use these tools to query Tripwire IP360 assets, audits, audited hosts, "
"and vulnerability catalogue data. Prefer narrow filters where possible."
),
)
# -----------------------------------------------------------------------------
# Low-level client helpers
# -----------------------------------------------------------------------------
class IP360Client:
def __init__(
self,
base_url: str,
username: str,
password: str,
verify_tls: bool = True,
timeout: int = 30,
) -> None:
if not base_url.endswith("/"):
base_url += "/"
self.base_url = base_url
self.verify_tls = verify_tls
self.timeout = timeout
self.session = requests.Session()
self.session.auth = HTTPBasicAuth(username, password)
self.session.headers.update(
{
"Accept": "application/json",
"User-Agent": "tripwire-ip360-mcp/1.0",
}
)
def _request(
self,
method: str,
path: str,
params: Optional[Dict[str, Any]] = None,
) -> Any:
url = urljoin(self.base_url, path.lstrip("/"))
response = self.session.request(
method=method.upper(),
url=url,
params=params,
verify=self.verify_tls,
timeout=self.timeout,
)
content_type = response.headers.get("Content-Type", "")
if not response.ok:
detail = None
try:
detail = response.json()
except Exception:
detail = response.text
raise RuntimeError(
f"IP360 API request failed: {response.status_code} {response.reason} | "
f"URL={yoururl} | Detail={detail}"
)
if "application/json" in content_type:
return response.json()
return response.text
def get(self, path: str, params: Optional[Dict[str, Any]] = None) -> Any:
return self._request("GET", path, params=params)
def get_client() -> IP360Client:
if not IP360_USERNAME or not IP360_PASSWORD:
raise RuntimeError(
"IP360 credentials not configured. "
"Set IP360_USERNAME and IP360_PASSWORD environment variables."
)
return IP360Client(
base_url=IP360_BASE_URL,
username=IP360_USERNAME,
password=IP360_PASSWORD,
verify_tls=IP360_VERIFY_TLS,
timeout=IP360_TIMEOUT,
)
def compact(obj: Dict[str, Any]) -> Dict[str, Any]:
"""Remove None values from query dicts."""
return {k: v for k, v in obj.items() if v is not None}
def paginate_all(
client: IP360Client,
path: str,
params: Optional[Dict[str, Any]] = None,
max_pages: int = 10,
) -> Dict[str, Any]:
"""
Collect paginated DRF-style responses:
{
"count": int,
"next": url|null,
"previous": url|null,
"results": [...]
}
Falls back cleanly if the endpoint returns a single object instead.
"""
params = dict(params or {})
results: List[Any] = []
page = 0
offset = int(params.get("offset", 0))
limit = int(params.get("limit", 100))
while page < max_pages:
page_params = dict(params)
page_params["limit"] = limit
page_params["offset"] = offset
data = client.get(path, params=page_params)
if isinstance(data, dict) and "results" in data:
results.extend(data.get("results", []))
if not data.get("next"):
return {
"count": data.get("count", len(results)),
"returned": len(results),
"results": results,
}
offset += limit
page += 1
continue
# Non-paginated response
return {
"count": 1 if data else 0,
"returned": 1 if data else 0,
"results": [data] if data else [],
}
return {
"count": len(results),
"returned": len(results),
"results": results,
"warning": f"Pagination stopped after {max_pages} pages",
}
# -----------------------------------------------------------------------------
# Formatting helpers
# -----------------------------------------------------------------------------
def slim_asset(asset: Dict[str, Any]) -> Dict[str, Any]:
return {
"id": asset.get("id") or asset.get("pk"),
"ip_address": asset.get("ip_address"),
"dns_name": asset.get("dns_name"),
"netbios_name": asset.get("netbios_name"),
"os": (
asset.get("os", {}).get("name")
if isinstance(asset.get("os"), dict)
else asset.get("os")
),
"last_seen": asset.get("last_seen"),
"in_tripwire_enterprise": asset.get("in_tripwire_enterprise"),
"score": asset.get("score"),
"url": asset.get("url"),
}
def slim_audit(audit: Dict[str, Any]) -> Dict[str, Any]:
return {
"id": audit.get("id") or audit.get("pk"),
"name": audit.get("name"),
"status": audit.get("status"),
"scan_type": audit.get("scan_type"),
"host_count": audit.get("host_count"),
"vuln_count": audit.get("vuln_count"),
"average_host_score": audit.get("average_host_score"),
"start_date": audit.get("start_date"),
"end_date": audit.get("end_date"),
"url": audit.get("url"),
}
def slim_audit_host(host: Dict[str, Any]) -> Dict[str, Any]:
os_name = None
if isinstance(host.get("operating_system"), dict):
os_name = host["operating_system"].get("name")
return {
"id": host.get("id") or host.get("pk"),
"ip_address": host.get("ip_address"),
"dns_name": host.get("dns_name"),
"netbios_name": host.get("netbios_name"),
"domain_name": host.get("domain_name"),
"operating_system": os_name,
"score": host.get("score"),
"timestamp": host.get("timestamp"),
"audit": host.get("audit"),
"url": host.get("url"),
}
def slim_vuln(vuln: Dict[str, Any]) -> Dict[str, Any]:
risk = vuln.get("risk")
risk_name = risk.get("name") if isinstance(risk, dict) else risk
return {
"id": vuln.get("id") or vuln.get("pk"),
"name": vuln.get("name"),
"cve": vuln.get("cve"),
"score": vuln.get("score"),
"cvssv3": vuln.get("cvssv3"),
"cvssv2": vuln.get("cvssv2"),
"risk": risk_name,
"publish_date": vuln.get("publish_date"),
"description": vuln.get("description"),
"url": vuln.get("url"),
}
# -----------------------------------------------------------------------------
# MCP tools
# -----------------------------------------------------------------------------
@mcp.tool
def health_check() -> Dict[str, Any]:
"""
Validate that the MCP server is configured to talk to Tripwire IP360.
"""
return {
"server": "Tripwire IP360 MCP",
"base_url": IP360_BASE_URL,
"username_configured": bool(IP360_USERNAME),
"password_configured": bool(IP360_PASSWORD),
"verify_tls": IP360_VERIFY_TLS,
"timeout_seconds": IP360_TIMEOUT,
}
@mcp.tool
def list_assets(
search: Optional[str] = None,
ip_address: Optional[str] = None,
dns_name: Optional[str] = None,
os_name_contains: Optional[str] = None,
in_tripwire_enterprise: Optional[bool] = None,
limit: int = 50,
max_pages: int = 2,
) -> Dict[str, Any]:
"""
List IP360 assets/hosts tracked across scans.
"""
client = get_client()
params = compact(
{
"search": search,
"ip_address": ip_address,
"dns_name": dns_name,
"os__name__icontains": os_name_contains,
"in_tripwire_enterprise": str(in_tripwire_enterprise).lower()
if in_tripwire_enterprise is not None
else None,
"limit": limit,
"offset": 0,
}
)
data = paginate_all(client, "/assets", params=params, max_pages=max_pages)
data["results"] = [slim_asset(x) for x in data["results"]]
return data
@mcp.tool
def get_asset(persistent_host_id: int) -> Dict[str, Any]:
"""
Get a single asset by persistent host ID.
"""
client = get_client()
asset = client.get(f"/assets/{persistent_host_id}")
return slim_asset(asset)
@mcp.tool
def list_audits(
name_contains: Optional[str] = None,
status: Optional[str] = None,
network_name: Optional[str] = None,
scan_profile_name: Optional[str] = None,
started_after: Optional[str] = None,
started_before: Optional[str] = None,
limit: int = 50,
max_pages: int = 2,
) -> Dict[str, Any]:
"""
List IP360 audit snapshots.
Date strings should be ISO-like values accepted by the IP360 API.
"""
client = get_client()
params = compact(
{
"name__icontains": name_contains,
"status": status,
"network__name__icontains": network_name,
"scan_profile__name__icontains": scan_profile_name,
"start_date__gte": started_after,
"start_date__lte": started_before,
"ordering": "-start_date",
"limit": limit,
"offset": 0,
}
)
data = paginate_all(client, "/audits", params=params, max_pages=max_pages)
data["results"] = [slim_audit(x) for x in data["results"]]
return data
@mcp.tool
def list_audited_hosts(
audit: Optional[str] = None,
ip_address: Optional[str] = None,
dns_name: Optional[str] = None,
domain_name: Optional[str] = None,
operating_system_contains: Optional[str] = None,
min_score: Optional[int] = None,
limit: int = 100,
max_pages: int = 2,
) -> Dict[str, Any]:
"""
List hosts discovered in an audit snapshot.
The 'audit' argument is the audit filter value exposed by the API.
"""
client = get_client()
params = compact(
{
"audit": audit,
"ip_address": ip_address,
"dns_name": dns_name,
"domain_name": domain_name,
"operating_system__name__icontains": operating_system_contains,
"score__gte": min_score,
"ordering": "-score",
"limit": limit,
"offset": 0,
}
)
data = paginate_all(client, "/audit/hosts", params=params, max_pages=max_pages)
data["results"] = [slim_audit_host(x) for x in data["results"]]
return data
@mcp.tool
def list_vulnerability_catalog(
search: Optional[str] = None,
cve: Optional[str] = None,
name_contains: Optional[str] = None,
min_score: Optional[float] = None,
min_cvssv3: Optional[float] = None,
risk_level: Optional[str] = None,
published_after: Optional[str] = None,
limit: int = 100,
max_pages: int = 2,
) -> Dict[str, Any]:
"""
List vulnerability definitions from the IP360 ASPL catalogue.
This is the catalogue of vulnerabilities IP360 can detect.
"""
client = get_client()
params = compact(
{
"search": search,
"cve": cve,
"name__icontains": name_contains,
"score__gte": min_score,
"cvssv3__gte": min_cvssv3,
"risk__level": risk_level,
"publish_date__gte": published_after,
"ordering": "-score",
"limit": limit,
"offset": 0,
}
)
data = paginate_all(client, "/aspl/vulns", params=params, max_pages=max_pages)
data["results"] = [slim_vuln(x) for x in data["results"]]
return data
@mcp.tool
def get_vulnerability(vuln_id: str) -> Dict[str, Any]:
"""
Get a single vulnerability definition by ID from the ASPL catalogue.
"""
client = get_client()
vuln = client.get(f"/aspl/vulns/{vuln_id}")
return slim_vuln(vuln)
@mcp.tool
def recent_posture_summary(
audit_name_contains: Optional[str] = None,
limit: int = 10,
) -> Dict[str, Any]:
"""
Return a compact summary of recent audits with host and vulnerability counts.
"""
audits = list_audits(
name_contains=audit_name_contains,
limit=limit,
max_pages=1,
)
results = audits.get("results", [])
if not results:
return {
"message": "No audits found",
"audits": [],
"totals": {
"host_count": 0,
"vuln_count": 0,
},
}
total_hosts = sum((x.get("host_count") or 0) for x in results)
total_vulns = sum((x.get("vuln_count") or 0) for x in results)
return {
"audits": results,
"totals": {
"host_count": total_hosts,
"vuln_count": total_vulns,
},
}
@mcp.tool
def raw_get(
endpoint: str,
query_json: Optional[str] = None,
) -> Dict[str, Any]:
"""
Escape hatch for querying arbitrary GET endpoints exposed by IP360.
Example endpoint:
/assets
/audits
/audit/hosts
/aspl/vulns
Example query_json:
{"limit": 20, "ordering": "-start_date"}
"""
client = get_client()
params = json.loads(query_json) if query_json else None
data = client.get(endpoint, params=params)
if isinstance(data, dict):
return data
return {"result": data}
if __name__ == "__main__":
mcp.run()
