UNPKG

akm-cli

Version:

akm (Agent Knowledge Manager) — a portable, local-first capability library for AI agents. Discover, load, share, and improve reusable skills, scripts, workflows, and knowledge across any shell-capable coding agent, including Claude Code, OpenCode, and Cur

github.com/itlackey/akm

itlackey/akm

109 lines (80 loc) • 6.34 kB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
# Security policy ## Supported versions Security fixes are made on the latest minor release line of `akm-cli`. The 0.x line is pre-1.0 — please upgrade promptly when a fix lands. | Version | Supported | | --- | --- | | 0.9.x | ✅ active | | 0.8.x | ❌ no longer maintained | | < 0.8 | ❌ no longer maintained | ## Reporting a vulnerability Please report security issues **privately** via GitHub Security Advisories: - https://github.com/itlackey/akm/security/advisories/new If GitHub Security Advisories is unavailable, email `itlackey@gmail.com` with the word `SECURITY` in the subject. Please include reproduction steps, the impacted akm version, and your operating environment. We will acknowledge receipt within 72 hours and aim to ship a fix or a mitigation guidance within two weeks, depending on severity. ## Threat model `akm` is a local CLI that reads and writes user files, executes user-authored shell commands (via scripts, workflows, and agent dispatch), and talks to explicitly configured external services (LLM endpoints, git remotes, npm, HTTP sources). It does **not** ship telemetry, send data to anyone by default, or open network listeners. See [`docs/reference/data-and-telemetry.md`](docs/reference/data-and-telemetry.md) for the on-disk inventory. Several akm surfaces execute user-controlled code or data with the full permissions of the akm process. These are documented design decisions, not bugs, but you should be aware of them: ### Workflows execute shell commands with full environment access Workflow steps run in your shell with your PATH and your environment variables — including any secrets you have exported or loaded via `akm env run` / `akm secret run`. **Only add workflow sources you trust.** See [`docs/reference/workflows.md` — "Security: workflow sources are executed code"](docs/reference/workflows.md#security-workflow-sources-are-executed-code) for the full discussion. ### Scripts execute shell commands `akm show scripts/<name>` returns a `run:` command line the user (or an integrating agent) then executes. The same trust model applies: scripts you install from third-party stashes are third-party code. ### Agents and commands embed user-authored prompts `akm show agents/<name>` and `akm show commands/<name>` return prompt templates and system prompts that an LLM will execute. A malicious stash maintainer could write a system prompt that instructs the LLM to read sensitive files in your working tree and exfiltrate them via the LLM response. Audit the prompt body the same way you'd audit a script. ### Installing a stash means trusting its code Installing a stash is not a data-only operation: **`<stashDir>/scripts/wiki-fetchers/*.{ts,js,mjs}` is imported and EXECUTED during `akm index`** (when a website-snapshot source in that stash is synced), with no gate, no prompt, and no allowlist. Every file in that directory is dynamically `import()`ed, and only *after* the module has fully evaluated does akm check that its default export looks like a fetcher (`{ name, matches, fetch }`) — module-level code (anything outside the exported functions) runs unconditionally before that check ever happens, and a file that fails the check still ran. There is no sandboxing: a wiki-fetcher script executes with the full permissions of the akm process, exactly like the scripts and workflow steps documented above. This is a deliberate design decision (owner ruling), not an oversight, and it will not change without a separate decision to add a gate. **If you install a stash from a source you do not trust, you are trusting its code to run on your machine at index time** — audit `scripts/wiki-fetchers/` the same way you would audit any other executable you're about to run, before installing. The built-in YouTube snapshot fetcher (`src/sources/snapshot-fetchers/youtube.ts`) deliberately **impersonates the YouTube Android app's InnerTube client** (`clientName: "ANDROID"`, a spoofed `clientVersion`) when calling YouTube's private `youtubei/v1/player` endpoint, because the public web client's caption URLs are Proof-of-Origin-Token gated and return empty bodies. This is known, intentional behavior needed to fetch captions at all, not a bug — documented here so it isn't mistaken for one. ### Environment and secret assets are plaintext on disk `env` and `secret` assets are owner-permissioned plaintext under `<stash>/env/` and `<stash>/secrets/`. They are protected against other local users by filesystem permissions but are not encrypted at rest. Do not commit these files to source control. Normal `akm env` and `akm secret` output never echoes values; materialize values only at the command boundary with `akm env run`, `akm secret run`, or `akm secret path`. The knowledge graph extracted from your assets (entities/relations) lives only in `$DATA/index.db` and is surfaced as aggregate counts via `akm health` (`--report` for the full breakdown) — there is no export command that writes graph content to an arbitrary path. ### Improve / propose send asset content to the configured LLM `akm improve` (whose strategies run processes such as reflect, distill, and consolidate) and `akm proposal new` can send asset frontmatter and body to the named LLM engine selected by the command, strategy, or current defaults. LLM connections live under `engines.<name>` in `~/.config/akm/config.json`. If you configure a third-party LLM, your asset content goes to that third party. Use a local engine endpoint (for example, `http://localhost:11434/v1/chat/completions` via Ollama) for assets containing secrets or private notes. ## Known non-issues - **The `akm-cli` npm package requires Node.js >= 22 as its bootstrap.** A working Bun >= 1.0 is preferred for execution when it is also on `PATH`; old, unusable, or absent Bun installations fall back to Node.js. Bun does not remove the package's Node.js requirement. Standalone binaries are runtime-free. This is a compatibility limitation, not a security risk. - **Workflows can read any file the akm process can read.** This is not a bug — see "Threat model" above. - **Installing `akm-cli` runs the preinstall hook.** The hook only validates the runtime version and exits non-zero when it is unsupported; it does not phone home or write outside the install directory.