Overview
botctl is an open-source process manager for autonomous AI agents, designed to run LLM-backed bots (currently Claude) as persistent background daemons on macOS, Linux, and Windows. Agents are configured via declarative YAML/Markdown (BOT.md) files, execute tool calls in a loop, maintain session memory across runs, and can be extended with third-party skill modules sourced from GitHub. While the project targets developer productivity use cases such as automated code review and API monitoring, its architecture aggregates several significant AI security risk vectors that warrant scrutiny from defenders deploying or evaluating agentic tooling.
Technical Analysis
Persistent Unattended Execution: Agents run as background OS processes on a configurable interval, invoking shell commands (<bash>), writing to the filesystem (<write>), and making external HTTP requests without per-action human approval. This is a textbook Excessive Agency pattern — the agent has the capability to act continuously with broad permissions and minimal oversight.
Skill Module Supply Chain: The botctl skills subsystem allows users to search and install skill modules directly from arbitrary GitHub repositories (botctl skills add owner/repo --skill slack-notify). Skills inject content into the bot’s system prompt. A malicious or compromised skill package therefore achieves prompt injection at the configuration layer — before any user-supplied instruction — and could redirect agent behaviour, exfiltrate workspace data, or escalate privileges within the agent’s tool scope.
Session Memory and Data Leakage: Every run persists its session to a local database. If the agent processes sensitive data (API keys in fetched content, PR diffs containing credentials, internal documentation), that data is retained in session storage and potentially accessible to subsequent skill modules or to an attacker with local access.
Unauthenticated Web Dashboard: The web UI defaults to http://localhost:4444 with no authentication mechanism described in the public documentation. In shared or multi-tenant environments, or where SSRF primitives exist, this exposes start/stop/message controls and full log streaming to any local process or proxied request.
Hot-Reload Prompt Manipulation: The hot-reload feature (BOT.md changes take effect on the next run without restart) means that any process or user with filesystem write access to the config file can silently alter the agent’s instructions mid-operation — a low-friction indirect prompt injection path.
Framework Mapping
- LLM01 / AML.T0051 (Prompt Injection): Skill modules inject directly into system prompts; hot-reload allows filesystem-level prompt manipulation.
- LLM05 / AML.T0010 (Supply Chain): Third-party GitHub-sourced skills are a direct supply chain vector.
- LLM08 (Excessive Agency): Persistent background execution with bash, write, and HTTP tool access with no mandatory human-in-the-loop.
- LLM06 / AML.T0057 (Sensitive Information Disclosure): Session memory retains all agent context including potentially sensitive fetched content.
- LLM07 (Insecure Plugin Design): The skills architecture lacks described sandboxing, signature verification, or permission scoping.
Impact Assessment
Organisations deploying botctl in CI/CD pipelines, developer workstations, or server environments are exposed to persistent unauthorised action if an agent is compromised via a malicious skill or prompt injection through processed external content. The blast radius scales with the tool permissions granted to the agent process.
Mitigation & Recommendations
- Verify skill provenance — audit all third-party skill modules before installation; prefer pinned commits over branch references.
- Restrict tool permissions — run agent processes under least-privilege OS accounts with scoped filesystem access.
- Authenticate the web dashboard — place the web UI behind a reverse proxy with authentication before any network exposure.
- Audit session storage — ensure sensitive data is not persisted in the session database unnecessarily.
- Human-in-the-loop gates — for high-consequence actions (PR comments, external API writes), require explicit approval steps in the bot prompt.