lorikeet-security-agent - Agentic exporter and runner for internal network p

项目说明

Lory Node Agent

!
!Python
!Status
!License

---

O

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-le independently - the exporter's job is to know e 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.

---

What's new in 0.2.0a2

Patch data has its own destination. The patch module's output and the posture collector's patch-compliance rollup are now posted to the platform's /v1/patch ingest, which drives the dedicated Patch Management page - per-host patch state and per-package rows - instead of landing in the generic finding queue. Discovery, in, supply chain, and other posture checks are unchanged. See Ingest routing.

Snapshot-based auto-resolve. A host's patch findings are sent as a single payload rather than split across batches, so the platform can treat them as a complete snapshot and close out packages that are no longer reported.

Graceful against older platforms. If /v1/patch returns 404, patch data falls back to /v1/findings for the rest of the run rather than being dropped.

Richer host detail. The patch collector now reports OS name and detected package manager, and sends a total_pending count alongside the capped package list so large update backlogs are not undercounted.

Pre in 0.2.0a1

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-mode stabilised. The combined continuous-collection + MCP stdio mode is now the recommended way to run when Lory is the primary orchestrator.

---

Why an agentic exporter

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 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 in 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-le.

---

Capabilities

Host & service discovery

Fingerprints the local host: open ports, listening services, and service . 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 OS database for every discovered package, and cross-references against known-malicious packages - no separate configuration required.

Patch & state

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 . Prioritizes by se and exploitability rather than raw C.

Server & application in

Builds and maintains a running in of operating systems, installed software, running services, listening ports, and notable configuration. Detects configuration drift and in changes over time.

Patch-management

Surfaces this host's patch compliance posture: whether it is current, lagging, or carrying known-exploited . Across a fleet of agents, this feeds a network-wide compliance view in the platform. Patch data is posted to a dedicated ingest path so it lands on the platform's Patch Management page as tracked per-host and per-package state, rather than as one-off findings - packages that stop being reported are resol. See Ingest routing.

Remediation tracking

Findings are fingerprinted (asset + check type + key detail) and tracked across cycles. When a finding is absent for a configurable number of consecuti it is automatically marked closed and a close notification is sent to the platform, so resol don't linger in the queue.

Structured findings export

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.

Lory AI integration

Exposes an MCP server so Lory AI can trigger collection cycles, retrie, 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-le (port scanning, banner grabbing, web probing) is handled by Lory's own toolbelt, not the exporter.

Agentic operation

Runs unattended. Schedules its own collection cycles, sequences modules, and persists finding state across restarts. The MCP server is a to Claude Desktop and any other MCP-compatible client for on-demand interaction alongside continuous collection.

---

Architecture

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 ne.

Outbound-only. The agent initiates all connections to the platform; the platform ne 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 ne the platform; only new or changed findings are shipped each cycle.

---

Collector modules

| Module | Collects | Notes |
| -------------- | ------------------------------------------------------------------------ | ----- |
| discovery | Local open ports, listening services, service , port churn - and local npm manifest crawl, OSV C, 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, OS name, package manager, installed-package manifest, C, EOL software | Se and exploitability-prioritized. Routed to the platform's Patch Management ingest, not the finding queue |
| in | OS/, installed software, running services, config drift | Tracks change over time |
| posture | Patch-compliance rollup across the fleet, known-exploited flags | Built on patch + in output; always runs last. The patch-compliance-rollup finding is routed to Patch Management; other posture checks go to the finding queue |

Modules are selected in configuration via the modules setting. Disabled modules consume no resources and contact no hosts.

---

MCP tools

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-le 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 se 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 se breakdown |
| | 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 |

---

Finding schema

All collectors emit findings in a single normalized en so the platform can ingest them uniformly:

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.

---

Scope & authorization

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

---

Installation

Requirements: Python 3.11+. No external binaries required.

Recommended: en (all platforms)

Editable installs (-e) mean local code changes take effect immediately without reinstalling.

> On Debian 12+ / Ubuntu 23.04+: The en method is the only reliable install path. These distributions enforce PEP 668 and additionally ship certain packages (e.g. typing_extensions) without a pip RECORD file. This means --break-system-packages cannot upgrade those packages even when the flag is passed, causing the install to abort. A ven this entirely — pip manages its own isolated copy of every dependency.

If cloning from GitHub is not possible (air-gapped / restricted hosts)

Copy the repository to the host by other means (scp, USB, shared , etc.), then install from the local directory:

The lk-exporter command is then a inside the activated venv. To run it without acti each time, call the ven directly:

System-wide install (not recommended on managed systems)

Some 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 abo.

All methods register the lk-exporter console entry point on your PATH.

---

Configuration

Configuration is supplied via a YAML config file (default config.yaml) or en . En take precedence over file .

Core settings

| 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 survi |
| 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, in, posture |
| concurrency | no | LK_CONCURRENCY | Max parallel host operations per cycle (default: 16) |
| log_level | no | LK_LOG_LEVEL | info (default), debug, warn, error |

#### Ingest routing

platform_url is a base; the agent posts to two paths beneath it:

| Path | Carries | Lands in |
| ---- | ------- | -------- |
| /v1/patch | the patch module's output plus the posture collector's patch-compliance-rollup | the platform's Patch Management page (host patch state + per-package rows) |
| /v1/findings | e else - discovery, in, supply chain, other posture checks | the platform's finding queue |

A host's patch findings are always sent as a single payload rather than split
across batches: the platform treats a payload containing patch-state as a
complete snapshot of that host and auto-resolves any package it no longer
reports.

If the platform has no /v1/patch endpoint, the first 404 falls back to
/v1/findings and pins that choice for the rest of the run, so a newer agent
ne patch data against an older platform.

Multi-agent mesh

| 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 |

Remediation tracking

| Setting | Required | Description |
| ------- | -------- | ----------- |
| auto_close_enabled | no | Auto-resol absent for auto_close_grace_cycles consecuti (default: true) |
| auto_close_grace_cycles | no | Consecuti a finding must be absent before it is auto-closed (default: 2) |

Webhooks

| Setting | Required | Description |
| ------- | -------- | ----------- |
| webhooks | no | List of {url, se, secret} objects. Fires an HMAC-signed HTTP POST per cycle for findings at or above the threshold |

Example config

---

Running the agent

By 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 -- / -v to see full INFO logs and the per-cycle findings table.

The CLI is also a as a module if the console script is not on your PATH:

--test-config is a quick sanity check for the default config.yaml: it 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 --config path.

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 ser. 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.

Standalone / SIEM mode

When platform_url is not set, findings print as newline-delimited JSON to stdout:

---

Multi-agent mesh

A single agent can only reach one network segment. When multiple agents are deployed across segmented en (internal LAN, DMZ, OT network, cloud VPC), they can form a mesh so the full network picture is without centralizing control.

How it works:
1. Each agent optionally runs a coordinator HTTP API (coordinator_port) that exposes its latest findings and discovered hosts.
2. Agents list their peers and pull findings + host lists from them after each collection cycle.
3. Pulled hosts are fed into downstream collectors so the local agent can assess assets it cannot directly discover.
4. 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).
5. A shared peer_secret authenticates peer-to-peer traffic.

---

Deployment patterns

Systemd service (continuous)

Cron / systemd timer (one-shot)

Docker

Claude Desktop (MCP)

Add to claude_desktop_config.json under "mcpServers":

Claude Desktop launches the process, connects o, and makes all MCP tools a in every con automatically.

Lory AI

Run the agent in --agent-mode so the MCP server is a alongside continuous collection:

Lory connects over MCP stdio to trigger cycles, pull findings, and coordinate across agents. Network-le (port scans, banner grabs, web probes) is handled by Lory's own toolbelt against data the agent surfaces.

---

Licensing

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:

When a platform_url pointing at the Lorikeet Security platform is configured, the agent 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 is also exercised during lk-exporter .

License keys may encode entitlements such as seat/agent count, enabled hosted features, and an expiry date, which the platform enforces at time. Treat the license key as a secret:

Supply it or secret manager, ne it to the repo.

Contact Lorikeet Security to rotate, extend, or revoke a key.

> Online means platform ingest requires outbound reachability to the platform. This does not affect standalone or self-hosted-sink operation.

---

Authentication

The agent authenticates to the platform with a per-agent token in the form:

Tokens are issued per deployment from the Lorikeet Security platform and scoped to a single engagement. Treat the token as a secret:

Supply it or secret manager, ne it to the repo.

Rotate it if it is e.

Revoke it from the platform when the engagement ends.

All traffic to the platform is authenticated and uses TLS; the channel is outbound-only.

---

Operational security

Scope-gated by default. No collection runs without an explicit allowlist.

License-gated ingest. Platform ingest requires a valid, online- license key; standalone collection runs without one.

Outbound-only transport. The agent initiates all connections to the platform; the platform ne into the network.

Least pri. 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 preser history across reinstalls.

---

Roadmap

Earlier phases harden the core collection loop; later phases deepen accuracy, broaden co, and extend orchestration on top of the existing MCP integration.

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 / in / posture collectors to GA, supply chain collector (npm + OS detection, bundled with discovery), MCP stdio server with 8 collection and mesh tools, pip-installable package with PyPI publish workflow, -- / --agent-mode / --test-config / CLI surface.

Phase 2 - Accuracy & depth planned
Credentialed deep in, authenticated config-audit collectors (CIS-style), ser fingerprinting, confidence scoring, dedup and correlation against history.

Phase 3 - Co expansion in progress
Supply chain: npm package discovery + OSV C + malicious-package detection *(shipped)*. Remaining: Acti 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-se 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- of select findings.

---

Contributing

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.

---

License

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.

项目信息

开发语言：Python

Star 数：5

技术要点

该项目属于防护思路方向的开源资源，代码结构清晰，适合安全研究人员学习参考。项目围绕Agentic exporter and runner for internal network pentesting, autonomous host discovery, patch/vulnerability state collection, and server/application inventory, surfaced as structured findings for the Lorikeet Security platform.展开，提供了可运行的实现，对理解相关安全机制、工具原理与攻防技术具有较高的研究价值。

从技术实现角度看，此类项目的核心在于对底层原理的深入理解与工程化落地。开发者在研究过程中可以结合官方文档与社区讨论，梳理项目的初始化流程、核心模块职责与数据流转，逐步掌握其中的技术细节与设计思路。

使用与学习建议

1. 下载源码压缩包，解压到本地环境。

2. 根据项目类型准备对应的运行环境与依赖。

3. 按照 README 中的步骤完成配置与部署。

4. 在隔离的测试环境中运行验证，避免影响生产系统。

免责声明

本资源来源于开源社区，仅供安全研究、技术学习与合法授权范围内的攻防演练使用，请勿用于任何非法或侵害他人权益的用途。使用本项目产生的一切后果由使用者自行承担。