The Lorikeet Security Agent Exporter is a lightweight, self-directed collection agent that runs on a host inside a client network. Focused on the machine it is deployed on, it continuously assesses local patch state, installed software, running services, open ports, and supply chain exposure - without requiring an operator to drive each cycle. Results are normalized into a consistent finding schema and shipped over an authenticated, outbound-only channel to the Lorikeet Security platform, where they feed into PTaaS workflows, dashboards, and reporting.
Lory AI connects to the agent over MCP to trigger collection cycles and pull findings. Lory's own pentest toolbelt handles broader network-level reconnaissance independently - the exporter's job is to know everything about the host it runs on and report it reliably.
Think of it as a per-host posture sensor: persistent, lightweight, and built to surface what changed on this machine and what is newly exploitable, not just what existed at install time.
- Phase 4 complete. All orchestration features are now shipped: on-demand MCP collection, multi-agent mesh coordination, remediation-tracking auto-close, and HMAC-signed alerting webhooks.
- MCP relay refactor. Pentest tools (port scanning, banner grabbing, web probing) have been removed from the exporter. Lory AI brings its own toolbelt and connects to the exporter solely for host posture data - cleaner separation of concerns, smaller attack surface on the deployed agent.
--agent-modestabilised. The combined continuous-collection + MCP stdio mode is now the recommended way to run when Lory is the primary orchestrator.
Traditional internal assessment is episodic. A tester connects, runs a fixed scan profile, exports results, and leaves. Between engagements the network drifts: hosts are added, patches lapse, services get exposed, and configurations rot. None of that is visible until the next engagement.
The agentic model changes the loop:
- Continuous, not point-in-time. The agent runs on a cadence (or continuously) and tracks state over time, so drift and regressions are caught as they happen.
- Host-focused. Each agent knows its own host deeply: installed packages, patch levels, running services, open ports, supply chain exposure. Network-wide recon is Lory's job.
- Low-touch deployment. Deploy one agent per host; they run unattended and report without operator involvement between cycles.
- Platform-native. Findings land directly in the Lorikeet Security platform in a structured form, ready for correlation against external ASM data and prior engagement history.
- AI-ready. Lory AI connects via MCP to trigger cycles, pull findings, and coordinate across agents - then applies its own pentest toolbelt for network-level investigation.
Fingerprints the local host: open ports, listening services, and service versions. Tracks newly exposed and newly closed ports between cycles so changes are surfaced immediately. Supply chain analysis is part of the discovery module: it crawls the local filesystem for npm manifests, queries the OSV vulnerability database for every discovered package, and cross-references against known-malicious packages - no separate configuration required.
Collects OS patch levels and installed-package manifests, then maps them against known-CVE data to flag missing patches, end-of-life software, and known-exploitable versions. Prioritizes by severity and exploitability rather than raw CVE count.
Builds and maintains a running inventory of operating systems, installed software, running services, listening ports, and notable configuration. Detects configuration drift and inventory changes over time.
Surfaces this host's patch compliance posture: whether it is current, lagging, or carrying known-exploited vulnerabilities. Across a fleet of agents, this feeds a network-wide compliance view in the platform.
Findings are fingerprinted (asset + check type + key detail) and tracked across cycles. When a finding is absent for a configurable number of consecutive cycles it is automatically marked closed and a close notification is sent to the platform, so resolved issues don't linger in the queue.
Normalizes all collected data into a single finding schema and streams it to the platform over an authenticated channel for triage, deduplication, and reporting. Standalone mode (no platform URL) prints findings as JSON to stdout for piping to a SIEM or custom sink.
Exposes an MCP server so Lory AI can trigger collection cycles, retrieve findings, and query agent state on demand. Lory uses this to feed fresh posture data into its reasoning loop during an engagement - for example, triggering a patch scan on a host of interest and immediately pulling the results. Network-level pentesting (port scanning, banner grabbing, web probing) is handled by Lory's own toolbelt, not the exporter.
Runs unattended. Schedules its own collection cycles, sequences modules, and persists finding state across restarts. The MCP server is available to Claude Desktop and any other MCP-compatible client for on-demand interaction alongside continuous collection.
flowchart TB
subgraph AGENT["EXPORTER AGENT · CLIENT INTERNAL NETWORK"]
SCHED["Scheduler\n(agentic loop)"]
SCOPE["Scope Enforcer\n(allowlist gate)"]
DISC["Discovery\n+ Supply Chain"]
PATCH["Patch / Vuln"]
INV["Inventory"]
POSTURE["Posture"]
NORM["Normalizer\n(finding schema)"]
SS["State Store\n(fingerprint · auto-close)"]
SCHED --> SCOPE
SCOPE --> DISC
SCOPE --> PATCH
SCOPE --> INV
SCOPE --> POSTURE
DISC --> NORM
PATCH --> NORM
INV --> NORM
POSTURE --> NORM
NORM --> SS
end
PLATFORM["Lorikeet Security Platform\ntriage · correlation · reporting"]
AI["AI Client\nLory · Claude Desktop"]
WH["Webhook Targets\nSIEM · alerting"]
PEERS["Peer Agents\nother segments"]
SS -->|"findings · outbound TLS"| PLATFORM
SS -->|"alerts · HMAC-signed"| WH
AGENT <-->|"MCP stdio"| AI
AGENT <-->|"peer pull"| PEERS
Design principles
- Scope enforcement is a hard gate, not a filter. Every target is checked against the configured allowlist before any collector touches it. Out-of-scope hosts are never contacted.
- Outbound-only. The agent initiates all connections to the platform; the platform never reaches into the network.
- Modular collectors. Each collector is independently enable/disable-able so deployments can be tuned to the engagement.
- Findings are fingerprinted. The same issue never floods the platform; only new or changed findings are shipped each cycle.
| Module | Collects | Notes |
|---|---|---|
discovery |
Local open ports, listening services, service versions, port churn - and local npm manifest crawl, OSV CVE lookup, malicious-package detection | Baseline module; recommended always-on. Supply chain analysis is built into this module and runs automatically with no extra config. |
patch |
OS patch level, installed-package manifest, CVE mapping, EOL software | Severity- and exploitability-prioritized |
inventory |
OS/version, installed software, running services, config drift | Tracks change over time |
posture |
Patch-compliance rollup across the fleet, known-exploited flags | Built on patch + inventory output; always runs last |
Modules are selected in configuration via the modules setting. Disabled modules consume no resources and contact no hosts.
When the agent runs in agent mode (lk-exporter run --agent-mode) or MCP-only mode (lk-exporter mcp), it exposes 8 tools over a stdio JSON-RPC channel. Lory AI uses these to trigger collection, pull findings, and coordinate across agents. Network-level pentest tools (port scanning, banner grabbing, web probing, nmap scripts) live in Lory's own toolbelt and are not part of this agent.
| Tool | Category | Description |
|---|---|---|
trigger_collection |
Control | Run an on-demand cycle - all enabled modules or a named subset |
get_findings |
Query | Return findings from the most recent cycle; filter by severity or module |
get_closed_findings |
Query | Return findings auto-closed by the remediation-tracking loop |
get_status |
Query | Agent health, scope summary, modules, last cycle time, and severity breakdown |
validate_scope |
Scope | Check whether a host or IP is inside the configured allowlist |
list_scope |
Scope | List all scope entries and estimated IP count |
list_peers |
Mesh | Health and status of all configured peer agents |
get_peer_findings |
Mesh | Pull findings from one or all peer agents |
All collectors emit findings in a single normalized envelope so the platform can ingest them uniformly:
{
"finding_id": "uuid",
"agent_id": "uuid",
"collected_at": "2026-06-06T00:00:00Z",
"module": "patch",
"target": {
"host": "10.0.4.12",
"hostname": "app-prod-04",
"in_scope": true
},
"category": "missing-patch",
"severity": "high",
"title": "Missing OS security update",
"evidence": {
"cve": ["CVE-2026-XXXXX"],
"installed_version": "1.2.3",
"fixed_version": "1.2.7"
},
"first_seen": "2026-06-01T00:00:00Z",
"last_seen": "2026-06-06T00:00:00Z",
"state": "open"
}first_seen, last_seen, and state give the platform the temporal context needed to distinguish new exposures from persistent ones and to auto-close findings that have been remediated.
This tool is for authorized internal assessment only.
The exporter enforces an explicit scope definition and will not collect against hosts outside the configured allowlist. The scope enforcer runs as a code-level gate ahead of every collector; there is no mode in which the agent operates without a scope.
Deploy only on networks you own or are contractually engaged to test. Unauthorized scanning of networks you do not control may be illegal in your jurisdiction.
Requirements: Python 3.11+. No external binaries required.
git clone https://github.com/Lorikeet-Security/lorikeet-security-agent-exporter.git
cd lorikeet-security-agent-exporter
python -m venv .venv
source .venv/bin/activate # Windows: .venv\Scripts\activate
pip install -e .Editable installs (-e) mean local code changes take effect immediately without reinstalling.
On Debian 12+ / Ubuntu 23.04+: The virtual environment method is the only reliable install path. These distributions enforce PEP 668 and additionally ship certain packages (e.g.
typing_extensions) without a pipRECORDfile. This means--break-system-packagescannot upgrade those packages even when the flag is passed, causing the install to abort. A venv sidesteps this entirely — pip manages its own isolated copy of every dependency.
Copy the repository to the host by other means (scp, USB, shared volume, etc.), then install from the local directory:
cd lorikeet-security-agent-exporter
python -m venv .venv
source .venv/bin/activate
pip install -e .The lk-exporter command is then available inside the activated venv. To run it without activating each time, call the venv binary directly:
/path/to/lorikeet-security-agent-exporter/.venv/bin/lk-exporter runSome Linux distributions (Arch, Debian 12+, Ubuntu 23.04+) enforce PEP 668 and block system-wide pip installs by default. Even with --break-system-packages, installs may fail on Debian-family systems when a dependency (e.g. typing_extensions) was installed by the OS package manager without a pip RECORD file. Use the venv path above instead.
# From PyPI
pip install lorikeet-security-agent-exporter --break-system-packages
# From source (after cloning)
pip install -e . --break-system-packages
# From GitHub (latest main)
pip install git+https://github.com/Lorikeet-Security/lorikeet-security-agent-exporter.git --break-system-packagesAll methods register the lk-exporter console entry point on your PATH.
Configuration is supplied via a YAML config file (default config.yaml) or environment variables. Environment variables take precedence over file values.
| Setting | Required | Env var | Description |
|---|---|---|---|
scope |
yes | - | CIDR ranges / hostnames the agent is authorized to touch |
agent_id |
no | - | Stable identity string. Auto-generated on first run and persisted to .lk_state/agent.json; pin here to survive reinstalls |
platform_url |
no | LK_PLATFORM_URL |
Lorikeet Security platform ingest endpoint (omit for standalone / self-hosted sink) |
license_key |
if platform | LK_LICENSE_KEY |
Platform license key. Required for platform ingest |
agent_token |
if platform | LK_AGENT_TOKEN |
Per-deployment agent authentication token |
interval |
no | LK_INTERVAL |
Collection cadence: continuous, or e.g. 6h, 24h, 30m |
modules |
no | - | Enabled collectors: discovery, patch, inventory, posture |
concurrency |
no | LK_CONCURRENCY |
Max parallel host operations per cycle (default: 16) |
log_level |
no | LK_LOG_LEVEL |
info (default), debug, warn, error |
| Setting | Required | Env var | Description |
|---|---|---|---|
coordinator_port |
no | LK_COORDINATOR_PORT |
Start a peer coordinator HTTP API on this port; disabled by default |
peer_secret |
no | LK_PEER_SECRET |
Shared Bearer token for peer-to-peer authentication |
peers |
no | - | List of peer coordinator URLs to pull findings and hosts from each cycle |
| Setting | Required | Description |
|---|---|---|
auto_close_enabled |
no | Auto-resolve findings absent for auto_close_grace_cycles consecutive cycles (default: true) |
auto_close_grace_cycles |
no | Consecutive cycles a finding must be absent before it is auto-closed (default: 2) |
| Setting | Required | Description |
|---|---|---|
webhooks |
no | List of {url, severity_threshold, secret} objects. Fires an HMAC-signed HTTP POST per cycle for findings at or above the threshold |
scope:
- 10.0.0.0/16
- 192.168.50.0/24
platform_url: https://lorikeetsecurity.com/ingest
license_key: ${LK_LICENSE_KEY}
agent_token: ${LK_AGENT_TOKEN}
interval: 6h
modules:
- discovery
- patch
- inventory
- posture
concurrency: 16
log_level: info
# Multi-agent mesh (optional)
coordinator_port: 8765
peer_secret: ${LK_PEER_SECRET}
peers:
- http://10.1.0.5:8765 # DMZ agent
- http://10.2.0.9:8765 # OT segment agent
# Remediation tracking
auto_close_enabled: true
auto_close_grace_cycles: 2
# Webhooks (optional)
webhooks:
- url: https://hooks.example.com/security
severity_threshold: high
secret: ${LK_WEBHOOK_SECRET}# show version and licensing info
lk-exporter --version
# quick config check (validates config.yaml and exits)
lk-exporter --test-config
# continuous agentic operation (quiet by default)
lk-exporter run
# one-shot collection cycle
lk-exporter run --once
# point at a specific config file
lk-exporter run --config /etc/lorikeet/config.yaml
# verbose output - full INFO logs and per-cycle findings table
lk-exporter run --verbose
# start the agent + MCP stdio server simultaneously (for Lory / Claude Desktop)
lk-exporter run --agent-mode
# full validation of config, scope, and platform reachability
lk-exporter validate
lk-exporter validate --config /etc/lorikeet/config.yaml
# start MCP stdio server only (no scheduled collection)
lk-exporter mcpBy default the agent runs quietly: after startup it prints a single status line and then a one-line summary per collection cycle (finding count with critical/high breakdown). Pass --verbose / -v to see full INFO logs and the per-cycle findings table.
The CLI is also available as a module if the console script is not on your PATH:
python -m lk_exporter run --once--test-config is a quick sanity check for the default config.yaml: it validates the file, enumerates the scope, and (if platform_url is set) checks the license key and platform reachability, then exits. For a non-default config path use lk-exporter validate --config path.
validate is recommended before every new deployment. It confirms the scope parses correctly and the allowlist is non-empty, and, if platform ingest is configured, that the license key is valid and the endpoint is reachable and authenticated, without contacting any target hosts.
run --agent-mode starts the background collection loop and the MCP stdio server simultaneously. Lory AI connects over MCP stdio to trigger on-demand cycles and pull findings.
mcp starts only the MCP server with no autonomous scanning. The AI client drives all activity via tool calls. Use this when you want the AI to be the sole orchestrator with no background scans between tool calls.
When platform_url is not set, findings print as newline-delimited JSON to stdout:
# pipe to jq for human-readable output
lk-exporter run --once | jq .
# stream into a file or forward to a SIEM ingestion endpoint
lk-exporter run | tee findings.jsonlA single agent can only reach one network segment. When multiple agents are deployed across segmented environments (internal LAN, DMZ, OT network, cloud VPC), they can form a mesh so the full network picture is visible without centralizing control.
How it works:
- Each agent optionally runs a coordinator HTTP API (
coordinator_port) that exposes its latest findings and discovered hosts. - Agents list their peers and pull findings + host lists from them after each collection cycle.
- Pulled hosts are fed into downstream collectors so the local agent can assess assets it cannot directly discover.
- Peer findings are correlated locally and displayed via MCP tools (
list_peers,get_peer_findings) but are not re-exported to the platform (to avoid double-counting). - A shared
peer_secretauthenticates peer-to-peer traffic.
# Agent on the internal LAN - runs coordinator and knows about the DMZ agent
coordinator_port: 8765
peer_secret: ${LK_PEER_SECRET}
peers:
- http://10.1.0.5:8765 # DMZ segment agent[Unit]
Description=Lorikeet Security Agent Exporter
After=network-online.target
Wants=network-online.target
[Service]
Type=simple
User=lk-exporter
WorkingDirectory=/opt/lk-exporter
EnvironmentFile=/opt/lk-exporter/.env
ExecStart=/opt/lk-exporter/.venv/bin/lk-exporter run
Restart=on-failure
RestartSec=30
[Install]
WantedBy=multi-user.target# /etc/cron.d/lk-exporter
0 */6 * * * lk-exporter /opt/lk-exporter/.venv/bin/lk-exporter run --once \
--config /opt/lk-exporter/config.yaml >> /var/log/lk-exporter.log 2>&1FROM python:3.12-slim
WORKDIR /app
COPY . .
RUN pip install -e . --no-cache-dir
VOLUME ["/app/.lk_state"]
ENTRYPOINT ["lk-exporter"]
CMD ["run"]docker run -d \
-v $(pwd)/config.yaml:/app/config.yaml:ro \
-v lk-state:/app/.lk_state \
-e LK_LICENSE_KEY=lk_lic_... \
-e LK_AGENT_TOKEN=lk_agent_... \
lorikeet-security-agent-exporterAdd to claude_desktop_config.json under "mcpServers":
"lk-exporter": {
"command": "/usr/local/bin/lk-exporter",
"args": ["mcp", "--config", "/etc/lorikeet/config.yaml"]
}Claude Desktop launches the process, connects over stdio, and makes all MCP tools available in every conversation automatically.
Run the agent in --agent-mode so the MCP server is available alongside continuous collection:
lk-exporter run --agent-mode --config /path/to/config.yaml
Lory connects over MCP stdio to trigger cycles, pull findings, and coordinate across agents. Network-level recon (port scans, banner grabs, web probes) is handled by Lory's own toolbelt against data the agent surfaces.
The agent is open source (MIT) and runs freely. You can clone it, read it, fork it, and run collection against your own scope without any key.
A license key is required only to ingest findings into the hosted Lorikeet Security platform. It is the platform entitlement, not a gate on the software itself. The key is separate from the agent_token: the license authorizes platform ingest, the token authenticates the connection. If you are running the agent standalone or exporting to your own sink, no license key is needed.
License keys are issued per customer from the Lorikeet Security platform and take the form:
lk_lic_<32 hex chars>
When a platform_url pointing at the Lorikeet Security platform is configured, the agent validates the license key online before streaming findings. If the key is missing, malformed, expired, or revoked, platform ingest is rejected; local collection still runs and can be exported elsewhere. License validation is also exercised during lk-exporter validate.
License keys may encode entitlements such as seat/agent count, enabled hosted features, and an expiry date, which the platform enforces at validation time. Treat the license key as a secret:
- Supply it via environment variable or secret manager, never commit it to the repo.
- Contact Lorikeet Security to rotate, extend, or revoke a key.
Online validation means platform ingest requires outbound reachability to the platform. This does not affect standalone or self-hosted-sink operation.
The agent authenticates to the platform with a per-agent token in the form:
lk_agent_<32 hex chars>
Tokens are issued per deployment from the Lorikeet Security platform and scoped to a single engagement. Treat the token as a secret:
- Supply it via environment variable or secret manager, never commit it to the repo.
- Rotate it if it is ever exposed.
- Revoke it from the platform when the engagement ends.
All traffic to the platform is authenticated and uses TLS; the channel is outbound-only.
- Scope-gated by default. No collection runs without an explicit allowlist.
- License-gated ingest. Platform ingest requires a valid, online-verified license key; standalone collection runs without one.
- Outbound-only transport. The agent initiates all connections to the platform; the platform never reaches into the network.
- Least privilege. Run the agent with the minimum OS access needed for its enabled modules.
- Auditable. Every collection cycle is logged with what was assessed and what was found.
- No exfiltration of payloads. The agent exports findings and metadata, not bulk data or file contents.
- State persisted locally. Finding fingerprints and the agent ID are stored in
.lk_state/on the agent host. Back up this directory if you need to preserve finding history across reinstalls.
Earlier phases harden the core collection loop; later phases deepen accuracy, broaden coverage, and extend orchestration on top of the existing MCP integration.
Phase 1 #################### 100% Core hardening (shipped)
Phase 2 ####................ ~20% Accuracy & depth
Phase 3 ###................. ~15% Coverage expansion (supply chain shipped)
Phase 4 #################### 100% Orchestration (shipped in 0.2.0a1)
Phase 5 .................... 0% Intelligence
Phase 1 - Core hardening shipped
Agentic scheduler and scope-enforcement gate, normalized finding schema with temporal state, outbound-only authenticated transport with token rotation, discovery / patch / inventory / posture collectors to GA, supply chain collector (npm + OSV + malicious-package detection, bundled with discovery), MCP stdio server with 8 collection and mesh tools, pip-installable package with PyPI publish workflow, --verbose / --agent-mode / --test-config / validate CLI surface.
Phase 2 - Accuracy & depth planned
Credentialed deep inventory, authenticated config-audit collectors (CIS-style), service-level fingerprinting, confidence scoring, dedup and correlation against history.
Phase 3 - Coverage expansion in progress
Supply chain: npm package discovery + OSV CVE lookup + malicious-package detection (shipped). Remaining: Active-Directory-aware discovery, pluggable CVE / threat-intel feeds, KEV and EPSS prioritization, cloud and hybrid asset discovery, container / Kubernetes collectors.
Phase 4 - Orchestration & automation shipped · 0.2.0a1
On-demand collection over MCP (shipped), Lory AI integration via MCP stdio - trigger_collection, get_findings, get_status (shipped), multi-agent coordination - per-agent coordinator HTTP server + peer pull client, list_peers / get_peer_findings MCP tools (shipped), remediation-tracking auto-close loop - finding fingerprinting, grace-cycle counter, synthetic close notifications (shipped), alerting webhooks - HMAC-signed HTTP POST on high-severity findings and close events, configurable per-target threshold (shipped), MCP relay refactor - pentest tools removed from the exporter; Lory brings its own toolbelt and connects to the exporter for host posture data only (shipped).
Phase 5 - Intelligence planned
Risk-based prioritization (exploitability x exposure x criticality), attack-path mapping, drift baselining with anomaly detection, optional safe-validation of select findings.
Contributions are welcome. Please open an issue to discuss substantial changes before submitting a pull request, keep collectors modular and scope-safe, and include tests where practical. By contributing you agree your contributions are licensed under the MIT License.
Authorized use only: regardless of license, this tool is for assessing systems you own or are explicitly authorized to test. Do not use it against systems without permission.
MIT License. Copyright (c) Lorikeet Corp (operating as Lorikeet Security).
See LICENSE for the full text. The MIT grant covers this agent and its source. The hosted Lorikeet Security platform and the issuance of license keys for platform ingest are separate commercial offerings and are not covered by this license.