{
  "markdown": "# armoctl\n\nCLI tool for instrumenting ECS task definitions with the ARMO runtime security agent.\n\n## 🤖 Use from Claude Code or Gemini CLI\n\narmoctl ships as a Claude Code plugin (and Gemini CLI extension) so AI assistants can drive the ARMO security platform directly: list incidents, triage CVEs, manage exception policies, generate network policies, and more.\n\n### Claude Code\n\n```\n/plugin marketplace add armosec/armoctl\n/plugin install armoctl@armosec\n```\n\nThe first time a session starts, the plugin checks for the `armoctl` binary on `PATH` and runs the official installer if it's missing. After that, the SessionStart hook keeps the binary on the same version as the plugin (running `armoctl update` whenever they drift).\n\n### Gemini CLI\n\n```\ngemini extension install https://github.com/armosec/armoctl\n```\n\nGemini CLI first tries to fetch a release-asset bundle and fails with a 404, then offers a `git clone` fallback — answer **Y** to that prompt and accept the one-time review of hooks/skills. The extension loads the same skills as the Claude plugin and the same SessionStart hook installs/updates the `armoctl` binary on the first session. No need to install the binary manually first.\n\n### What's in the plugin\n\n- A root `armoctl` skill covering setup, the JSON output contract (`--full` / `--fields` / `--query`), the mutation safety contract (`--dry-run` / `--yes`), and error semantics.\n- 13 per-cluster skills (`armoctl-incidents`, `armoctl-vulns`, `armoctl-posture`, `armoctl-risks`, `armoctl-attack-chains`, `armoctl-inventory`, `armoctl-network-policies`, `armoctl-seccomp`, `armoctl-runtime-rules`, `armoctl-runtime-policies`, `armoctl-integrations`, `armoctl-cloud-accounts`, `armoctl-repo-posture`) auto-loaded by description match when the user's task touches that cluster.\n- A SessionStart hook that ensures the binary is present and version-matched.\n\n### Configure once\n\nYou'll need two credentials:\n\n- **Customer GUID** — find it in the ARMO Platform UI, top-right account dropdown.\n- **Access key** — generate one at <https://cloud.armosec.io/settings/workspace/agent-access-keys> (or <https://cloud.us.armosec.io/settings/workspace/agent-access-keys> for US tenants).\n\nPick whichever path fits the situation:\n\n**Through the AI assistant (recommended for chat-driven setup).** Paste both credentials into the conversation and let the assistant run:\n\n```bash\necho \"<ACCESS_KEY>\" | armoctl configure \\\n    --customer-guid \"<CUSTOMER_GUID>\" \\\n    --access-key-stdin\n```\n\nReading the key from stdin keeps it out of shell history and `ps` listings. The command validates against the ARMO API and exits non-zero if the credentials are rejected.\n\n**Interactive on the terminal (no AI involvement):**\n\n```bash\narmoctl configure\n```\n\nWalks you through Customer GUID, Access Key, and API URL via a TUI. Saved to `~/.armoctl/config.yaml`.\n\n**Environment variables (CI / containers / one-off shells):**\n\n```bash\nexport ARMO_CUSTOMER_GUID=...\nexport ARMO_ACCESS_KEY=...\nexport ARMO_API_BASE_URL=api.armosec.io   # default; override for staging\n```\n\nOnce configured, the agent can run any read-only command directly. Mutations require `--dry-run` for the preview and `--yes` to commit (or a confirmation prompt on a TTY).\n\n## 📦 Install\n\n```bash\ncurl -fsSL https://package-distribution.armosec.io/armoctl/install.sh | bash\n```\n\n## 🔨 Build\n\n```bash\nmake armoctl\n```\n\n## 🔑 Authentication\n\nMost armoctl commands talk to the ARMO platform API and require credentials — the API-backed skills (incidents, vulnerabilities, posture, risks, attack chains, runtime rules/policies, network policies, seccomp, integrations, cloud accounts, repository posture, inventory) authenticate with `customer-guid` and `access-key`. Local helpers like the per-cluster `fields` cheatsheets work offline.\n\nThe legacy ECS commands (`ecs patch`, `ecs instrument`) are the exception: previewing a patched task definition works offline; only `--register` and `--deploy` need credentials.\n\nConfigure credentials once with `armoctl configure` (see [Configure once](#configure-once) for the chat-driven, interactive, and env-var paths). They persist to `~/.armoctl/config.yaml` (mode 0600). Env vars (`ARMO_CUSTOMER_GUID`, `ARMO_ACCESS_KEY`, `ARMO_API_BASE_URL`, and `ARMO_API_URL` for the legacy ECS/version-check host) override the config file for the current shell.\n\n## 📋 Commands\n\n### `ecs patch` — Patch a task definition file\n\nTakes a task definition JSON, injects the ARMO ptrace sidecar, and outputs the patched version.\n\n```bash\n# From a file\narmoctl ecs patch task-definition.json\n\n# From stdin\ncat task-definition.json | armoctl ecs patch -\n\n# From an ARN (fetches from AWS)\narmoctl ecs patch arn:aws:ecs:us-east-1:123456789:task-definition/my-task:1\n\n# Patch only specific containers\narmoctl ecs patch --container web --container api task-definition.json\n\n# Patch and register with AWS\narmoctl ecs patch --register task-definition.json\n\n# Use a custom agent image\narmoctl ecs patch --agent-image 015253967648.dkr.ecr.eu-north-1.amazonaws.com/ecs-ptrace-agent:v1.0.0 task-definition.json\n```\n\n### `ecs instrument` — Instrument a live ECS service\n\nFetches the current task definition from a running service, patches it, and optionally deploys the update.\n\n```bash\n# Preview the patched output\narmoctl ecs instrument -c my-cluster -s my-service\n\n# Patch, register, and deploy\narmoctl ecs instrument -c my-cluster -s my-service --deploy\n```\n\n### `version` — Display version info\n\n```bash\narmoctl version\n```\n\n## ⚙️ What the patcher does\n\nWhen you patch a task definition, armoctl:\n\n1. Adds a `sidecar-ptrace` container running the ARMO agent with `SYS_PTRACE` capability\n2. Wraps each target container's command to launch through the ptrace shim\n3. Sets `pidMode` to `\"task\"` for cross-container visibility\n4. Adds `shared-data` and `profiles-data` volumes\n5. Optionally adds a `volume-fixer` init container that prepares shared volumes (`--volume-fixer`)\n\nContainers without a `command` (relying on image ENTRYPOINT/CMD) are instrumented via dependency and volume mounts but their entrypoint is not modified.\n\n## 🚩 Flags reference\n\n### Credential flags (`armoctl configure` only)\n\n| Flag | Env var | Description |\n|------|---------|-------------|\n| `--customer-guid` | `ARMO_CUSTOMER_GUID` | ARMO customer GUID. |\n| `--access-key` | `ARMO_ACCESS_KEY` | ARMO API access key. Avoid in shell history; prefer `--access-key-stdin`. |\n| `--access-key-stdin` | | Read the access key from stdin. Recommended for scripts and AI agents. |\n| `--api-base-url` | `ARMO_API_BASE_URL` | Agent-bridge API host used by every skill cluster (default: `api.armosec.io`). |\n| `--api-url` | `ARMO_API_URL` | Legacy backend host used by ECS operator install and version-check (default: `cloud.armosec.io`). |\n\nEnv vars are also honored by the rest of armoctl at runtime, regardless of whether `armoctl configure` was used.\n\n### ECS flags\n\n| Flag | Description |\n|------|-------------|\n| `--agent-image` | Agent sidecar image (default: `015253967648.dkr.ecr.eu-north-1.amazonaws.com/ecs-ptrace-agent:latest`). |\n| `--container` | Container names to patch (repeatable; default: all). |\n| `--volume-fixer` | Include a volume-fixer init container to chmod the shared volume. |\n| `--register` | Register the patched task definition with AWS (`patch` only, requires credentials). |\n| `--deploy` | Register and deploy to the live service (`instrument` only, requires credentials). |\n| `-c`, `--cluster` | ECS cluster name or ARN (`instrument` only). |\n| `-s`, `--service` | ECS service name or ARN (`instrument` only). |\n\n### Global flags\n\nInherited from the root command. The output/query/pagination flags apply to API-backed skill commands that go through the shared response renderer; local helpers like `configure`, `ecs patch`, and the per-cluster `fields` cheatsheets write their output directly and ignore them.\n\n| Flag | Description |\n|------|-------------|\n| `--output` | Output format: `json` (default), `yaml`, `ndjson`, `table`, `csv`. |\n| `--query` | gojq expression applied to the response. |\n| `--fields` | Comma-separated dotted paths to keep. |\n| `--full` | Disable summary projection; return raw response. |\n| `--limit` | Max items to fetch when auto-paging (default 500, 0 = no cap). |\n| `--page` / `--page-size` | Explicit pagination. |\n| `--dry-run` | Build the request and print the would-be payload without sending it. Recommended preview before any mutation. |\n| `--yes` | Skip the confirmation prompt for mutations (required when stdin is not a TTY). |\n| `--debug` | Enable debug mode. |\n",
  "bytes": 8580,
  "sha": "82bd232c525a2f2fab9e04932e45953a19894e127d83c387ddfcb2d64f0eb85c",
  "repo_slug": "armosec/armoctl",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_armosec_armoctl_armo_ctrl_0e9ac2d7/readme"
}