tenable-patch-management-logs-mcp

An MCP server that does the log digging for Tenable Patch Management (TPM) SaaS. Point it at your tenant's server logs (the Admin Portal zip) and client logs (device folders, collector bundles, or a log requested from a client), then ask questions like "why are my Tenable VM vulnerabilities not showing up in TPM?" or "what changed on the server in the last 24 hours?".

The server does the analysis. Parsing, de-duplication across logs, error-code decoding, known-issue matching and threshold comparisons all happen in Python; tools return finished, structured results (verdict, ranked issues with counts and fixes, findings with reasoning) instead of piles of raw lines for the model to add up.

What it gives you

Safety properties worth knowing:

• Read-only. Sources are never modified. Every write stays in the data dir: data/sources.json (sources added with add_log_source), an extracted copy of each bundle under data/bundles, and data/baselines.db when you call record_baseline_snapshot - which stores device names, components, normalised signatures, days and counts, never message text.

• Nothing that looks like a credential is returned. TPM writes the Tenable VM access key into VulnerabilityManagement.log and adaptiva.err in plain text; 64-hex key material, token: / password= / secretKey= values, bearer tokens and URL passwords are masked to their last 4 characters. Host names, IPs, e-mail addresses, GUIDs and client IDs are kept because troubleshooting needs them.

• No silent truncation. Each call reads at most 1 GB / 5,000 files (newest first); anything not read is listed in coverage with how to narrow the call. Lines in an unrecognised format are never merged into one entry.

• Bundles are extracted defensively: path-traversal entries are skipped, and extraction stops at 8 GB or 100,000 files.

• No network access and no Tenable API keys. TPM has no documented public API; everything comes from its logs.

Related MCP server: Log Analyzer MCP Server

What it reads

SaaS only. Self-hosted Adaptiva OneSite servers are out of scope: their server logs name a SQL Server database and carry ntlmauth.log, and check_log_sources flags a source like that as unsupported_source instead of analysing it as a tenant. Client logs are the same either way, but nothing in the knowledge base, the playbooks or the remediation advice assumes a server you run yourself.

Requirements

• Python 3.11+

• uv

• TPM logs (see above). No Tenable credentials are needed.

Setup

uv sync --extra dev

Optionally copy .env.example to .env to preconfigure sources:

cp .env.example .env

Sources can also be added in conversation with add_log_source, which is usually easier for support bundles.

Run the server directly (it speaks MCP over stdio, so it will just sit there waiting for a client - that is the correct behaviour):

uv run python -m tenable_patch_management_logs_mcp

Connecting a client

Use the absolute path to this folder in the config below.

Claude Desktop

Edit claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "tenable-patch-logs": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\tenable-patch-management-logs-mcp",
        "run",
        "python",
        "-m",
        "tenable_patch_management_logs_mcp"
      ],
      "env": {
        "TPM_LOG_SOURCES": "saas-server=C:\\cases\\acme\\logs.zip;clients=C:\\cases\\acme\\TPM-Logs-20260917"
      }
    }
  }
}

Restart Claude Desktop afterwards. If uv is not on the launcher's PATH, use its absolute path ((Get-Command uv).Source / which uv) as command. The env block is optional.

Claude Code

claude mcp add tenable-patch-logs -- uv --directory /absolute/path/to/tenable-patch-management-logs-mcp run python -m tenable_patch_management_logs_mcp

Add --env TPM_LOG_SOURCES=... to preconfigure sources, or add the same block as above to a project-level .mcp.json.

Getting the logs

• Server: Admin Portal → gear icon → Logs → Download All Server Logs. The zip contains adaptiva-server/ with adaptiva*.log, adaptiva.err, componentlogs/ and workflowlogs/. Downloading it twice gives two slightly different snapshots; use the newer one.

• Clients, several at once (Windows):

  .\collect\Collect-TPMLogs.ps1 -ComputerName WS-BAD07, WS-GOOD01 -Days 3

  One folder per device, zipped, plus the Client Validator results from the registry. Include a healthy device so compare_devices has something to compare against.

• Linux / macOS clients: sudo ./collect/collect-tpm-logs.sh 3 /tmp (tar.gz, includes the adaptivaclientd journal).

• One client from the console: 10.2.973.9 and later can request a log file from a client; the download (<clientId>_adaptiva.log) can be registered as is.

Example questions to ask once connected

• "Add C:\cases\acme\logs.zip as acme-saas and check the log sources."

• "Summarise what's wrong on the TPM server over the last 7 days, ignoring noise."

• "Why is Tenable VM data not showing up in Patch Management?" (runs diagnose vm_integration)

• "Why did patching fail on WS-BAD07 yesterday? Decode the exit codes."

• "Build a timeline for WS-BAD07 from 30 minutes before the first installer failure."

• "What does WS-BAD07 have that WS-GOOD01 doesn't?"

• "Anything new or spiking in the last 24 hours compared with the week before?"

• "Which clients is the server retrying messages to?"

• "The server logs in UTC and these clients in Singapore time - line them up and show me the timeline."

• "Record a baseline snapshot now, so next week's comparison still has this week."

How the analysis works

Parsing. Log layouts were taken from real TPM 10.2.973.9 logs (a SaaS server bundle and a Windows client), plus the standard Windows Installer log:

Multi-line messages (the component suffix can sit on a later line) and stack traces stay attached to their entry. Rotated files (adaptiva.2.log, Feeds.1.log, .gz) are read as one log.

De-duplication. TPM writes an error to adaptiva.log or a component log and to adaptiva.err. Events are matched on device, timestamp, level, thread and message, and counted once (duplicate_lines_in_other_logs reports how many repeats were removed).

Severity. TPM sometimes logs real failures at INFO. The documented Services-sensor issue, for example, is an INFO line carrying an exception. Entries with a stack trace or a non-zero Adaptiva Error Code are raised to ERROR and flagged with raised_from_lower_level.

Known issues (tenable_patch_management_logs_mcp/knowledge.py) each carry a confidence:

• documented: described by Tenable or Adaptiva, with a source link (for example the 9.2 Services-sensor DLL issue, or the 9.1.965.x client upgrade failure).

• observed: seen in real TPM 10.2.973.9 logs, explained from the message and surrounding lines (for example Tenable VM keys rejected with "not related to any active containers", periodic feed check failures, CDN publication failures, clients rejected for missing install authentication).

• generic: standard Java, Windows, SQL or network errors.

Issues with impact: none are platform noise (for example the SQL Server monitoring query that fails daily on the SaaS PostgreSQL database, or receipt-cleanup warnings). About two thirds of the warning and error events in the real SaaS bundle were noise. They are counted under noise, not listed as issues.

Error codes are decoded from context: MSI / Win32 exit codes (1603, 1618, 3010), HRESULTs including HRESULT_FROM_WIN32 values (0x80070643), Windows Update (0x8024xxxx), component servicing (0x800Fxxxx), negative decimal HRESULTs and HTTP statuses. Adaptiva's own Error Code = N values are shown but never decoded as Windows errors.

Anomalies compare a window with the period before it, read from the same logs, so no state has to build up. Thresholds are constants at the top of tenable_patch_management_logs_mcp/anomaly.py and are echoed in every result:

Each finding is judged against the log(s) it appears in. A log that only started recently is not reported as a spike just because the device's other logs go back further. Days that have rotated away are filled in from recorded snapshots when there are any (see Baselines that survive rotation); every result says how many days came from the logs and how many from the store.

Time. Relative windows (90m, 24h, 7d, 2w) count back from the newest entry in the selected logs, not from now, so an old support bundle still gives sensible results. Pass anchor="now" to measure from this machine's clock instead, or an ISO time to measure from a moment. Whatever the anchor, any device whose logs end well before it is listed in devices_behind_anchor with how far behind it is, so a quiet device is never mistaken for a healthy one. Timestamps are shown as written unless zones are configured (see Time zones); TPM 10.2 SaaS server logs and Windows client logs were observed to be in UTC.

Fitting it to your environment

Time zones

TPM timestamps carry no zone, so a server logging in UTC and a client logging in Asia/Singapore sit eight hours apart in a merged timeline. Declare what each one writes and everything is converted into a single display zone before any window, timeline or comparison is worked out:

TPM_LOG_TIMEZONES=saas-server=UTC;WS-BAD07=Asia/Singapore;*=UTC
TPM_DISPLAY_TIMEZONE=Asia/Singapore

Keys match a source name first, then a device name, then *. Values are IANA names, fixed offsets (+08:00), UTC or local (this machine). add_log_source(..., timezone="+08:00") sets it for one source. Every result says what was converted, and names any device left as written - nothing shifts silently. Lines that carry their own offset (2026-09-10T08:15:02+0800) are converted from that offset whatever the configuration says. Without configuration nothing is converted, exactly as before.

Your own known issues

The built-in catalog cannot know your environment. A knowledge file adds signatures, marks noise you have already decided to ignore, and decodes the PatchDeploymentResult numbers Tenable does not document - no code change, picked up on the next call:

{
  "known_issues": [
    {
      "id": "acme_proxy_407",
      "title": "Proxy rejects client downloads (ticket OPS-4711)",
      "pattern": "407 Proxy Authentication Required",
      "impact": "high",
      "explanation": "Our proxy asks TPM clients to authenticate, which they cannot do.",
      "remediation": "Allow *.adaptiva.cloud through the proxy without inspection."
    },
    { "id": "acme_chatter", "title": "Cleanup message we ignore", "pattern": "receipts.*no in-memory cleanup", "impact": "none" }
  ],
  "patch_deployment_results": {
    "operation_status": { "3": "Failed" },
    "reason_code": { "3010": "Success, reboot required" }
  }
}

Only id, title and pattern are required; impact: none marks noise. Entries are matched before the built-in ones, so reusing a built-in id replaces it. Rejected entries are listed with the reason by check_log_sources - a knowledge file never fails silently. See examples/known_issues.example.json.

Baselines that survive rotation

detect_log_anomalies compares a window with the days before it in the same logs, so a heavily rotated log gives it a short baseline (findings then carry low_confidence). Recording a snapshot keeps the daily counts after the file they came from is gone:

# after each collection, or on a schedule against a live log folder
uv run python -c "from tenable_patch_management_logs_mcp import anomaly, sources; \
print(anomaly.record_baseline_snapshot(sources.SourceRegistry(), since='30d')['message'])"

Each device is then asked only for the days its own logs no longer reach, so nothing is counted twice, and baseline_history in every result says which days came from where. Re-recording a day keeps the larger count, so running it twice cannot inflate a baseline. Deleting data/baselines.db deletes the history.

Layout

tenable_patch_management_logs_mcp/
  __main__.py      python -m tenable_patch_management_logs_mcp
  server.py        MCP entrypoint and the twelve tool definitions
  sources.py       Source configuration, bundle extraction, device / role / rotation detection
  logformat.py     Line layouts, multi-line entries, encodings, time spans
  classifier.py    Redaction, signatures, severity, known-issue matching, extractions
  error_codes.py   Win32 / MSI / HRESULT / Windows Update / CBS / HTTP code decoding
  knowledge.py     Log catalog, known issues, playbooks, version advisories, where to get logs
  customknowledge.py  Your own known issues and PatchDeploymentResult meanings, loaded from a file
  timezones.py     Which zone each log is written in, and the zone results are shown in
  history.py       Recorded daily baselines (SQLite), so anomalies survive log rotation
  analysis.py      Scoped, bounded scanning; summaries, search, timelines, playbooks, comparisons
  anomaly.py       Window-versus-baseline findings, thresholds and snapshot recording
examples/
  known_issues.example.json   Starting point for your own known issues and value mappings
collect/
  Collect-TPMLogs.ps1    Windows collector (local or WinRM), one folder per device
  collect-tpm-logs.sh    Linux / macOS collector
scripts/
  smoke_local.py   Offline end-to-end run of every tool
  live_check.py    Read-only run against your configured logs
tests/
  sample_logs.py   Synthetic, sanitised logs in the real layouts
  test_*.py

Dependency direction is one-way: server → {analysis, anomaly} → {classifier, sources, history} → {logformat, error_codes, knowledge, customknowledge, timezones}.

Testing

1. Unit tests (no network)

uv run pytest -q

232 tests covering every layout, rotation and encoding, bundle extraction guards, device/role detection, redaction, signatures, severity escalation, known issues, site knowledge files, zone conversion, window anchoring, recorded baselines, every playbook, anomaly thresholds and the tool contracts. All fixtures are synthetic (tests/sample_logs.py); no real log content is stored in the repository.

2. Offline end-to-end

uv run python scripts/smoke_local.py

Registers a synthetic SaaS server bundle, a two-device client bundle and a single requested client log through the tools, calls every tool, and asserts the results: duplicates counted once, noise set aside, planted secrets redacted, known issues found, bad input returned as a structured error. Exits non-zero on any failure, so it works as a CI gate.

3. Against your logs (read-only)

uv run python scripts/live_check.py 7d

Uses the same configuration as the server and prints sources, the zone / knowledge / baseline configuration in force, the error summary, the playbooks relevant to the logs you have, and anomalies. On a real 80 MB SaaS bundle a 7-day summary took about 4 seconds, an unfiltered search about 6, and the slowest call measured - a 30-day summary across every file - about 9.

4. Through an MCP client

npx @modelcontextprotocol/inspector uv --directory . run python -m tenable_patch_management_logs_mcp

Or connect Claude Desktop / Claude Code (above) and ask one of the example questions.

Known limitations

• Formats validated on 10.2.973.9 server logs and a Windows client adaptiva.log. Linux and macOS clients use the same Java logging and are expected to match, but have not been checked against real samples. check_log_sources lists any file whose format was not recognised.

• Client component logs were not in the real samples. The playbooks for _SDMErrors.log, SoftwareInstaller.log and WindowsPatching.log rely on exit codes, HRESULTs, exceptions and the documented PatchDeploymentResult line rather than exact message wording. Add the wording you meet to your own knowledge file; no code change is needed.

• PatchDeploymentResult status and reason values are undocumented. They are shown as logged, and failure evidence comes from non-zero reason codes and exceptions. Map the values your console shows under patch_deployment_results and they are decoded alongside them.

• Time zones have to be declared. TPM writes local timestamps with no zone, so no tool can detect one: set TPM_LOG_TIMEZONES (or timezone on add_log_source) when logs come from machines in different zones. Anything without a declared zone is shown as written and named in the results rather than guessed at.

• Recorded baselines start when you start recording. record_baseline_snapshot cannot recover days that rotated away before its first run, and it keeps counts per day, so a burst inside one day is judged against that whole day.

• The knowledge base is a starting point. Built-in issues marked observed come from one tenant's logs; confirm fixes against current Tenable documentation, and put what your own environment keeps seeing into a knowledge file.

Disclaimer

Not affiliated with, endorsed by, or supported by Tenable, Inc. or Adaptiva. "Tenable", "Tenable Patch Management", "Tenable Vulnerability Management" and "Adaptiva" are trademarks of their respective owners. This project reads log files you already have; it is an independent troubleshooting aid, not a Tenable product, and its findings should be confirmed against current vendor documentation before you act on them.

Sources

• Tenable Patch Management docs: client logs, server logs, client install logs, Client Validator, SaaS vs self-hosted, 2025 and 2026 release notes.

• Adaptiva (the TPM platform): logging configuration, Services sensor issue (9.2), client upgrade issue (9.1.965), 10.0.971 known issues, feature updates.