Skip to main content
Glama
tenable-activity-mcp

tenable-activity-mcp

by brendanong95

tenable-activity-mcp

Tests

An MCP server that exposes the Tenable Vulnerability Management audit/activity log (GET /audit-log/v1/events) as a small set of tools, so any MCP client can ask about platform activity, API-key usage, and anomalous behaviour on demand.

The server does the analysis. Counting, grouping, rate math and threshold comparisons all happen in Python; tools return finished, structured results (failure_rate_pct, by_actor, findings with reasoning) rather than dumping raw events for the model to add up.

What it gives you

Tool

Purpose

list_activity_events

Event feed for a window, with actor/action filters. Pagination is followed automatically; returns a resumable next_token if a safety cap is hit.

summarize_activity

Deterministic rollup for a window: counts by actor, action, CRUD type and access type, plus failure/anonymous rates.

get_api_key_usage

API-key-driven activity only, grouped by actor: action breakdown, distinct source IPs, first/last seen.

detect_anomalies

Compares a window against each actor's stored baseline. Flags new actors, volume spikes, unseen source IPs, failed-event bursts, sustained failure rates, off-hours spikes and never-before-seen actions - each with evidence and a reasoning sentence.

get_actor_profile

One actor's full picture: role (best effort), all-time action breakdown, access types, every source IP seen.

check_permission_prereqs

Pass/fail on whether the configured keys can actually read the audit log, with remediation text.

Safety properties worth knowing:

  • Nothing that looks like a credential is ever returned. Field values whose key names a secret (secret_key, api_key, token, password, ...) or whose value looks like Tenable key material are masked to their last 4 characters.

  • Pagination is capped at 20 pages / 100k events per tool call; hitting the cap is reported explicitly along with the cursor needed to continue.

  • 429s back off using the X-RateLimit-Reset header (the endpoint sends no Retry-After), with exponential fallback and a retry ceiling.

Related MCP server: tenable-mcp-server

Requirements

  • Python 3.11+

  • uv

  • Tenable VM API keys whose owner can read the audit log

Tenable role / permissions

Reading audit-log/v1/events requires the Administrator role, or a custom role with explicit audit-log read permission, on the user that owns the API keys. Anything less gets HTTP 403; check_permission_prereqs reports that in plain language.

Generate keys in Tenable VM under Settings → My Account → API Keys. The keys inherit the permissions of the user that created them.

get_actor_profile additionally tries to resolve an actor's role from the user directory. If the keys cannot list users, the profile is still returned - just without the role label.

Setup

uv sync --extra dev

Then copy .env.example to .env and fill in your keys:

cp .env.example .env

Verify credentials and permissions before wiring it into a client:

uv run python -c "from dotenv import load_dotenv; load_dotenv(); from src.server import check_permission_prereqs; print(check_permission_prereqs())"

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 src.server

Connecting a client

Use the absolute path to your clone in the config below. To print it, run pwd from the repository root on macOS/Linux, or (Get-Location).Path in PowerShell.

Claude Desktop

Edit claude_desktop_config.json:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "tenable-activity": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\tenable-activity-mcp",
        "run",
        "python",
        "-m",
        "src.server"
      ],
      "env": {
        "TENABLE_ACCESS_KEY": "your_access_key",
        "TENABLE_SECRET_KEY": "your_secret_key",
        "TENABLE_MCP_BASE_URL": "https://cloud.tenable.com"
      }
    }
  }
}

Restart Claude Desktop afterwards. On macOS/Linux use a POSIX path (/Users/you/tenable-activity-mcp).

If uv is not on the launcher's PATH, use its absolute path (which uv / (Get-Command uv).Source) as command.

Claude Code

claude mcp add tenable-activity --env TENABLE_ACCESS_KEY=your_access_key --env TENABLE_SECRET_KEY=your_secret_key -- uv --directory /absolute/path/to/tenable-activity-mcp run python -m src.server

Or add the same block as above to a project-level .mcp.json.

Credentials passed via env take precedence over .env; the .env file is a local-development convenience, and either mechanism works.

Example questions to ask once connected

  • "Check whether my Tenable credentials can read the audit log."

  • "Summarise Tenable platform activity for the last 7 days - who was most active, and what's the failure rate?"

  • "Which API keys were used against Tenable in the last 30 days, and from which source IPs?"

  • "Look for anomalies in Tenable activity over the past 3 days against a 30-day baseline, and explain anything you flag."

  • "Show me everything actor 00000000-1111-4222-8333-444444444444 has ever done - actions, access types, and IPs."

How anomaly detection works

detect_anomalies needs history to compare against, which lives in a local SQLite file (state.db, created automatically):

  1. If stored baselines are older than BASELINE_REFRESH_MAX_AGE_HOURS (12), the server fetches the baseline_days immediately preceding your window and recomputes per-actor averages, known IPs, known actions and an hour-of-day histogram.

  2. Your window is fetched and compared against those baselines.

  3. Events in the analysed window are not folded into the baseline, so re-running the same window returns the same findings.

Every threshold is a named constant at the top of src/anomaly.py and is echoed back in each result under thresholds:

Constant

Default

Meaning

SPIKE_MULTIPLIER

3.0

Window events/day must exceed this multiple of the baseline average

SPIKE_MIN_WINDOW_EVENTS

20

Floor before a spike can be flagged at all

NEW_IP_LOOKBACK_DAYS

30

How recently an IP must have been seen to count as "known"

FAILED_AUTH_BURST_COUNT / FAILED_AUTH_BURST_WINDOW_MINUTES

5 / 10

Failure-clustering trigger

HIGH_FAILURE_RATE_PCT

50.0

Sustained failure-rate trigger (over at least 10 events)

OFF_HOURS_START_HOUR / OFF_HOURS_END_HOUR

20 / 6 (UTC)

Off-hours band

OFF_HOURS_RATIO_MULTIPLIER

2.0

Off-hours share must exceed this multiple of the actor's baseline share

Baselines are per actor, so a service account that legitimately runs 500 scans a day does not get flagged for doing exactly that.

Layout

src/
  server.py          MCP entrypoint (FastMCP-style) + the six tool definitions
  tenable_client.py  Auth, filter building, cursor pagination, 429 backoff, typed errors
  classifier.py      API-key vs UI/session tagging, IP extraction, redaction, rollups
  anomaly.py         Thresholds and the individual anomaly checks
  state.py           SQLite: cursors, accumulated actor history, computed baselines
tests/
  test_pagination.py test_classifier.py test_anomaly.py

Dependency direction is one-way: server → {anomaly, classifier, state} → tenable_client.

Testing

Three levels, in the order you should run them.

1. Unit tests (no credentials, no network)

uv run pytest -q

105 tests covering pagination/cursor handling, rate-limit backoff, API-key vs session classification, redaction, and every anomaly threshold. Every API response is faked through a stub transport, so the suite never touches a live tenant.

2. Offline end-to-end (no credentials, no network)

uv run python scripts/smoke_local.py

Runs all six tools against a scripted fake Tenable (a quiet baseline month, then a noisy night from a new IP) and asserts the results: anomalies flagged, planted secrets redacted, bad input returned as a structured error instead of an exception. Exits non-zero on any failure, so it works as a pre-commit or CI gate.

3. Live check against your tenant (read-only)

With .env filled in:

uv run python scripts/live_check.py 7

Verifies audit-log permissions first and stops with remediation text if they are wrong, then prints a real summary, API-key usage breakdown, anomaly findings, and the busiest actor's profile for the last N days (default 7). All calls are GETs; nothing is written to Tenable.

4. Through an MCP client

Any MCP client works. To poke at the tools interactively without a chat client:

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

Or wire it into Claude Desktop / Claude Code (above) and ask one of the example questions. check_permission_prereqs is the right first call - it confirms the server started, found its credentials, and can reach the audit log.

Inspecting local state

uv run python -c "from src.state import StateStore; print(StateStore().stats())"

Delete state.db to reset baselines; the next detect_anomalies call rebuilds them.

Known limitations

  • Requires the Administrator role. Reading audit-log/v1/events needs the Administrator role, or a custom role with explicit audit-log read permission, on the user that owns the API keys. Anything less returns HTTP 403. Run check_permission_prereqs first - it reports exactly this, with remediation text.

  • Anomaly detection needs history before it is useful. The first detect_anomalies call against a fresh state.db builds baselines from the 30 days preceding your window and then compares against them. Actors with little or no prior activity flag as new_actor, so early runs are noisier than later ones.

  • Role resolution is best effort. get_actor_profile tries to resolve an actor's Tenable role from the user directory. If the keys cannot list users, the profile is still returned - just without the role label.

  • Off-hours detection uses a fixed UTC band. The off-hours window is 20:00-06:00 UTC and does not adjust to the tenant's working timezone. Distributed teams will see off-hours findings that are simply another region's working morning.

  • Baselines are local to the machine running the server. state.db is not shared between installs, so two operators running their own copies build independent baselines and can reach different conclusions about the same window.

  • Wide windows return partial results by design. One tool call follows at most 20 pages / 100,000 events. Hitting that cap is reported explicitly along with the next_token needed to resume, so it is never a silent truncation - but a very large window does take several calls.

  • Only the first 1,000 events come back inline. list_activity_events caps the inline events array at 1,000 and sets inline_truncated when it does. The summary block still covers every event fetched, so the aggregate numbers stay correct even when the inline list is trimmed.

  • get_actor_profile looks back 365 days at most, and cannot see further back than the audit log itself retains.

Notes

  • Built against mcp==2.0.0, where the SDK renamed FastMCP to MCPServer. server.py imports whichever name the installed SDK provides, so it also works on mcp 1.x.

  • Event fetching goes through pyTenable's TenableIO session (audit_log.events(..., return_json=True)), which keeps auth and connection handling in the maintained library while leaving the pagination.next cursor visible to us. If pyTenable is unavailable, an equivalent requests transport using the X-ApiKeys: accessKey=...;secretKey=... header takes over.

  • Timestamps are UTC everywhere, including the off-hours band.

  • state.db accumulates per-actor history. Delete it to reset all baselines; the next detect_anomalies call rebuilds them.

Available Tools

6 tools
check_permission_prereqsA

Verify the configured API keys can actually read the audit log.

Makes one minimal audit-log request and reports pass/fail with a plain explanation and remediation steps. Run this first when another tool returns an authentication or permission error. No secret material is echoed - the access key is shown with only its last 4 characters.

Returns: A dict with ok, a human-readable message, remediation when failing, plus configuration and local-state diagnostics.

Inputs: no named parameters. Returns: object

detect_anomaliesA

Compare a window against each actor's stored baseline and flag outliers.

Checks run: previously unseen actor, event volume above SPIKE_MULTIPLIER x the actor's historical daily average, source IPs absent from the baseline lookback, failed-event bursts, sustained high failure rate, off-hours activity spikes, and never-before-seen action types. Every finding includes the observed value, the threshold crossed, and a reasoning sentence.

Baselines live in the local SQLite state file and are refreshed from the period immediately preceding the window when they are stale. Events in the analysed window itself are not folded into the baseline, so re-running the same window yields the same findings.

Args: date_from: Start of the window under investigation, ISO-8601. date_to: End of the window under investigation, ISO-8601. baseline_days: Days of history preceding the window to baseline against.

Returns: A dict with findings (severity-ordered, each with evidence and reasoning), findings_by_type/findings_by_severity counts, and the active thresholds.

Inputs: date_to (required), date_from (required), baseline_days. Returns: object

get_actor_profileA

Full historical view of one actor: roles, actions, access types, IPs.

Combines a fresh audit-log fetch for the actor with everything previously persisted in the local state database, so IPs and actions seen in earlier sessions still show up. The Tenable role is resolved on a best-effort basis from the user directory and is omitted when the API keys cannot list users.

Args: actor_id: The actor UUID (as it appears in actor.id on events). lookback_days: How far back to fetch fresh events for this actor.

Returns: A dict with identity, recent_activity (rollup over the lookback window), lifetime (accumulated state: all IPs, all actions, all access types, first/last seen) and pagination.

Inputs: actor_id (required), lookback_days. Returns: object

get_api_key_usageA

Report API-key-driven activity per actor (UI/session activity excluded).

Events are classified as API-key driven using the audit event's access/auth-method field, falling back to user-agent shape (scripted client vs browser). Each actor gets an action breakdown, distinct source IPs, and first/last seen timestamps - all pre-aggregated.

Args: actor_id: Optional actor UUID. Omit to cover every actor with API-key activity in the window. date_from: Start of the window, ISO-8601. Defaults to 30 days ago. date_to: End of the window, ISO-8601. Defaults to now.

Returns: A dict with actors (per-actor API-key usage profiles), an access_type_totals breakdown for context, and coverage metadata.

Inputs: date_to, actor_id, date_from. Returns: object

list_activity_eventsA

List Tenable audit-log events for a date range, with optional filters.

Pagination is handled internally (the next cursor is followed automatically) up to a safety cap of 20 pages / 100k events per call; if the cap is hit, pagination.next_token is returned so the next call resumes exactly where this one stopped. Every event is normalised, tagged with an access type (API key vs UI session), and has credential-looking field values redacted to their last 4 characters.

Args: date_from: Start of the window, ISO-8601 (e.g. "2024-01-01" or "2024-01-01T00:00:00Z"). Inclusive. date_to: End of the window, ISO-8601. Inclusive. actor_id: Optional actor UUID to filter on (actor_id.eq). action: Optional exact action name, e.g. "user.create" (action.eq). limit: Page size sent to the API (1-5000). next_token: Opaque cursor from a previous call, to resume pagination.

Returns: A dict with events (classified, redacted), a summary rollup of those events, and a pagination block.

Inputs: date_to (required), date_from (required), limit, action, +2 more. Returns: object

summarize_activityA

Summarise all audit-log activity in a window (counts computed in Python).

Returns event counts by actor, by action, by CRUD type and by access type, plus failure and anonymous rates - all pre-computed. Use these numbers directly; do not re-derive them from raw events.

Args: date_from: Start of the window, ISO-8601. Inclusive. date_to: End of the window, ISO-8601. Inclusive.

Returns: A dict with a summary block (total_events, by_actor, by_action, by_crud, by_access_type, failure_rate_pct, top_failed_actions) and a pagination block describing coverage.

Inputs: date_to (required), date_from (required). Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 6 tools

    Disambiguation5/5

    Each tool targets a clearly different concern: raw event listing, summary rollups, API-key-specific usage, anomaly detection, actor profiling, and prerequisite checks. Even the two aggregation tools (summarize_activity and get_api_key_usage) are separated by access-type scope, and their descriptions reinforce the distinction.

    Naming Consistency5/5

    All tool names follow a consistent snake_case verb_noun pattern: list_activity_events, summarize_activity, get_api_key_usage, detect_anomalies, get_actor_profile, check_permission_prereqs. The verbs clearly signal the action and the objects clearly signal the resource or concern, making the set predictable and easy to navigate.

    Tool Count5/5

    Six tools is well-scoped for an audit-log activity server: two raw/aggregate views, two analysis-focused tools, one deep-dive tool, and one operational prerequisite check. Each tool earns its place without redundancy or bloat.

    Completeness5/5

    The tool surface covers the full audit-monitoring lifecycle: listing raw events, summarizing them, isolating API-key usage, detecting anomalies, profiling individual actors, and verifying access prerequisites. The automatic pagination and baseline handling close potential dead ends, so an agent can move from raw data to insight without missing critical operations.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • F
      license
      Not graded
      quality
      D
      maintenance
      Exposes Azure Log Analytics workspace data with tools for querying AuditLogs and AzureActivity tables, supporting custom KQL queries, time range filters, and pagination.
      -
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server for Tenable Vulnerability Management and the Tenable One platform, enabling LLMs to query assets, vulnerabilities, scans, exposure metrics, attack paths, and more via natural language.
      2
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Enables read-only querying of Azure Log Analytics and Azure Resource Graph through MCP, supporting KQL queries, workspace discovery, and resource inventory exploration with Azure RBAC authentication.
      11
      70 npm
      2
      MIT
    • F
      license
      Not graded
      quality
      C
      maintenance
      Read-only MCP server for querying Microsoft Purview unified audit logs across M365 workloads, wrapping the Graph API's asynchronous audit log search.
      -