为疯狂的 Agent 制定合理的策略。

网站：theharbinger.in

Harbinger 是一个非人类身份（NHI）和 Agent 安全平台。每个 AI Agent、机器人和服务账号都会获得一个加密身份（mTLS）；它发出的每个请求在获准前都要接受策略检查；而它所需的任何真实密钥都会从你自己的密钥库中提取，并在边缘处替换注入，因此 Agent 本身永远不会持有长期凭证。

其所属类别是广义的非人类身份安全（API 密钥、服务账号、机器人令牌），AI Agent 只是其中最突出、增长最快的应用案例，而不是一个仅面向 AI 的工具。

如今大多数“AI Agent 安全”平台，要么是要求你重写 Agent 以对接的 SDK，要么是只能告诉你现有哪些凭证、却不改变其使用方式的发现/治理仪表盘，要么只是把责任从一个 API 密钥转移到另一个 API 密钥。Harbinger 采用了不同的方法：

1. **无需修改代码：**Harbinger 是一个透明的 mTLS MITM 代理。只需将 Agent 流量指向网关，即可获得保护；这也适用于你无法控制的第三方 Agent 框架——而如今大多数 Agent 代码正是如此。

2. **密钥访问在结构上而非仅在流程上受到控制。**每个携带凭证的请求都会接受两个问题的检查：该 Agent 是否允许访问这个网站？该 Agent 是否允许针对这个网站使用这项凭证？只有两个答案都为“是”，Agent 才能使用该凭证。

3. 配置管理员凭证：

   cd deploy/docker cp .env.example .env

   edit .env and set a real ADMIN_PASSWORD

4. 运行 docker compose 文件：

   docker compose up --build

构建完成后，pki-init 会自动将 hbg_cli、harbinger_agentd 和 root_ca.crt 放入主机上的 deploy/docker/client-bundle/。如果 Agent 将在另一台机器上运行，请先将整个目录复制到该机器。

注意：只有 root_ca.crt 与这次部署相关；hbg_cli 和 harbinger_agentd 并非如此，因此只要与操作系统和架构匹配，它们可以来自其他任何位置（例如 GitHub release）。

3. 注册一个 Agent。

   cd deploy/docker/client-bundle ./hbg_cli cert install --cert root_ca.crt ./hbg_cli agent install --agent my-agent --ip 10.0.0.5 --user admin

此操作会提交注册请求并等待批准。可在 Web UI（http://localhost:8446，位于 Agent Enrollment）中批准，也可使用 CLI；随后重新运行相同命令以完成注册：

./hbg_cli agent install --agent my-agent

这将在默认的 ~/.config/harbinger_agentd/ 下写入 my-agent.crt/.key、缓存根 CA，并生成 agentd.yml。然后通过 harbinger_agentd 运行 Agent，它会将其流量代理至网关：

harbinger_agentd run --agent my-agent -- <YOUR_AGENT_COMMAND>
# example
harbinger_agentd run --agent my-agent -- opencode
# or create an alias if it's not a workflow
alias opencode="harbinger_agentd run --agent my-agent -- opencode"

4. 在 Agent 流量中注入密钥（可选）。

在 Web UI 中，进入 Vault Integration → Local：在 Secrets 下添加一个密钥，然后在下方部分创建一个目标。该目标会将策略可引用的名称映射至真实密钥所在位置，以及该密钥允许发送到的目的地（系统会自动为你添加 local: 前缀）。如果更倾向于脚本化操作，对应的 CLI 命令为：

hbg_cli admin target create --name slack-bot-token --secret-ref local:slack-bot-token --host slack.com

有关密钥库侧的设置（包括使用 AWS 而非本地密钥库），请参阅 docs/agent-secret-placeholders.md。

然后，在 Agent 当前读取真实令牌的位置，改为放置占位符：

export SLACK_BOT_TOKEN='hbg-secret:slack-bot-token:'

Harbinger 仅会针对策略明确允许使用该目标的 Agent 发往 slack.com 的请求，替换注入真实值。

管理服务器和网关服务器被有意设计为独立进程，这不仅是为了提升部署灵活性，也为了实现攻击面不对称。网关面向具有对抗性的 Agent 流量和实时密钥获取；管理端则掌握 CA/用户管理权限，且绝不直接处理 Agent 流量。

flowchart LR
    Agent["Agent / Bot<br/>(agent code)"]
    Sys["Your systems<br/>(Slack, GitHub, etc.)"]
    Admin["Harbinger Admin<br/>(control plane)<br/>CA · DB · policy/vault storage<br/>enrollment review · UI/CLI auth"]

    subgraph Gateway["Harbinger Gateway"]
        direction TB
        V["1. verify cert"] --> P["2. check policy"] --> I["3. inject secret"]
    end

    Agent -- "mTLS (agent cert)" --> Gateway
    Gateway -- "real API credential<br/>substituted at the edge" --> Sys
    Admin -- "signed edge config<br/>(policy, CRL, targets)" --> Gateway

加载中

Agent 从一开始就不会获得真实凭证。它们会被配置为使用占位符（hbg-secret:secret-mapping:）；只有在策略明确授权该 Agent 使用该目标，并且确认请求实际发往已注册的目的地、而非只是声称发往该目的地后，网关才会替换注入真实值。有关完整机制，包括第二项检查为何重要（它能够阻止遭到提示词注入的 Agent 将密钥泄露至攻击者控制的主机），请参阅 docs/agent-secret-placeholders.md。

每个 Agent 都会通过真实的 mTLS 证书完成注册：

1. Agent 自行生成密钥对和 CSR，并提交请求，同时指定其所属的用户账号。
2. 该用户（或任何管理员）审核并批准该请求。
3. Agent 通过网关完成注册；网关会验证 CSR 自身的签名及管理员签署的批准信息，然后签发真实的 mTLS 证书。
4. 撤销操作会通过已签名的边缘配置将更新后的 CRL 推送至所有网关，因此访问权限不会像未轮换的共享 API 密钥那样，在失去效用后仍悄然持续存在。

信任被划分在四层 CA 层级（Root CA -> Admin CA / Gateway CA / Agent CA）中，因此某一个 CA 被攻破并不会导致其他 CA 一并失守。例如，泄露的 Gateway CA 无法伪造 Agent 证书，而泄露的 Agent CA 也无法注册伪造网关。

• **将 harbinger_agentd 用作 Agent 沙箱：**目前，它包装并控制 Agent 的网络流量；下一步，它还将捕获 Agent 试图在主机上运行的命令，并在执行前拦截高风险命令，将策略执行范围从“它可以调用什么”扩展至“它可以做什么”。
• **更多密钥库提供商：**目前支持 AWS 和本地密钥；接下来将支持 GCP Secret Manager 和 Bitwarden。

采用 Apache License, Version 2.0 授权。

Sane policies for insane agents.

Website: theharbinger.in

Harbinger is a non-human identity (NHI) and agentic security platform. Every AI agent, bot, and service account gets a cryptographic identity (mTLS), every request it makes is checked against policy before it's allowed, and any real secret it needs is pulled from your own vault and swapped in at the edge, so the agent itself never holds a standing credential.

The category is non-human identity security in general (API keys, service accounts, bot tokens), with AI agents as the sharpest and fastest-growing example of it, not an AI-only tool.

Most "AI agent security" platforms today are either an SDK you have to rewrite your agent against, a discovery/governance dashboard that tells you what credentials exist without changing how they're used, or something that just shifts responsibility from one API key to another. Harbinger takes a different approach:

1. No code change required: Harbinger is a transparent mTLS MITM proxy. Point an agent's traffic at the gateway and it's covered, including third-party agent frameworks you don't control, which is most agent code today.

2. Secret access is structurally, not just procedurally, gated. Each request with credentials gets checked against two questions: is the agent allowed to access this website, and is the agent allowed to use this credential against this website? Only when both are true does the agent get to use the credential.

3. Configure admin credentials:

cd deploy/docker
cp .env.example .env
# edit .env and set a real ADMIN_PASSWORD

2. Run the docker compose file:

docker compose up --build

Once the build finishes, pki-init automatically drops hbg_cli, harbinger_agentd, and root_ca.crt into deploy/docker/client-bundle/ on the host. If the agent will run on a different machine, copy that whole directory there first.

Note: Only root_ca.crt is specific to this deployment; hbg_cli and harbinger_agentd aren't, so they could come from anywhere else (e.g. a GitHub release) as long as it matches your OS and architecture.

3. Enroll an agent.

cd deploy/docker/client-bundle
./hbg_cli cert install --cert root_ca.crt
./hbg_cli agent install --agent my-agent --ip 10.0.0.5 --user admin

This submits the enrollment request and waits for approval. Approve it from the web UI (http://localhost:8446, under Agent Enrollment) or use the CLI, then re-run the same command to complete enrollment:

./hbg_cli agent install --agent my-agent

This writes my-agent.crt/.key, caches the root CA, and generates agentd.yml, all under ~/.config/harbinger_agentd/ by default. Then run the agent under harbinger_agentd, which proxies its traffic through the gateway:

harbinger_agentd run --agent my-agent -- <YOUR_AGENT_COMMAND>
# example
harbinger_agentd run --agent my-agent -- opencode
# or create an alias if it's not a workflow
alias opencode="harbinger_agentd run --agent my-agent -- opencode"

4. Inject a secret into the agent's traffic (optional).

In the web UI, go to Vault Integration → Local: add a secret under Secrets, then create a target in the section below it, this maps a name your policy can reference to where the real secret lives and which destination it's allowed to go to (the local: prefix is applied for you). CLI equivalent, if you'd rather script it:

hbg_cli admin target create --name slack-bot-token --secret-ref local:slack-bot-token --host slack.com

See docs/agent-secret-placeholders.md for the vault-side setup (including AWS instead of local).

Then wherever your agent currently reads its real token from, put the placeholder there instead:

export SLACK_BOT_TOKEN='hbg-secret:slack-bot-token:'

Harbinger swaps in the real value only for requests to slack.com from an agent whose policy explicitly allows this target.

Admin and gateway servers are deliberately separate processes, not just for hosting flexibility but for attack-surface asymmetry. The gateway faces adversarial agent traffic and live secret-fetching; admin holds CA/user-management authority and never touches agent traffic directly.

flowchart LR
    Agent["Agent / Bot<br/>(agent code)"]
    Sys["Your systems<br/>(Slack, GitHub, etc.)"]
    Admin["Harbinger Admin<br/>(control plane)<br/>CA · DB · policy/vault storage<br/>enrollment review · UI/CLI auth"]

    subgraph Gateway["Harbinger Gateway"]
        direction TB
        V["1. verify cert"] --> P["2. check policy"] --> I["3. inject secret"]
    end

    Agent -- "mTLS (agent cert)" --> Gateway
    Gateway -- "real API credential<br/>substituted at the edge" --> Sys
    Admin -- "signed edge config<br/>(policy, CRL, targets)" --> Gateway

Loading

Agents are never given a real credential to begin with. They're configured with a placeholder (hbg-secret:secret-mapping:), and the gateway swaps in the real value only after policy explicitly authorizes that agent for that target and confirms the request is actually headed to the registered destination, not just claiming to be. See docs/agent-secret-placeholders.md for the full mechanics, including why that second check matters (it's what stops a prompt-injected agent from exfiltrating a secret to an attacker-controlled host).

Every agent enrolls with a real mTLS certificate:

1. The agent generates its own keypair + CSR and submits it, naming the user account it belongs to.
2. That user (or any admin) reviews and approves the request.
3. The agent completes enrollment with the gateway, which verifies the CSR's own signature plus the admin's signed approval, then issues a real mTLS certificate.
4. Revocation pushes an updated CRL to all gateways via signed edge config, so access doesn't silently outlive its usefulness the way an un-rotated shared API key does.

Trust is split across a four-tier CA hierarchy (Root CA -> Admin CA / Gateway CA / Agent CA), so a compromise of one CA doesn't hand over the others. For example, a leaked Gateway CA can't forge agent certificates, and a leaked Agent CA can't register a fake gateway.

• harbinger_agentd as an agent sandbox: today it wraps an agent's network traffic; next it'll also capture the commands the agent tries to run on the host and block risky ones before they execute, extending policy enforcement from "what it can call" to "what it can do."
• More vault providers: AWS and local secrets are supported today; GCP Secret Manager and Bitwarden are next.

Licensed under the Apache License, Version 2.0.