BLACKSHIELD

Guia público

Deploy the Security Agent

Run BlackShield's governed Go security agent inside your environment with tenant-scoped assignments, MCP context, AI Gateway controls, and approval gates around every mutation. Público: Security engineers, platform engineers, and security operations teams. Tempo típico de configuração: 5 minutes.

quickstart

Use isto se

Run BlackShield's governed Go security agent inside your environment with tenant-scoped assignments, MCP context, AI Gateway controls, and approval gates around every mutation.

Audience
Security engineers, platform engineers, and security operations teams
Typical time
5 minutes

Antes de começar

  • Confirm the tenant is on a plan with Security Agents enabled and `/agents` is visible to the admin team.
  • Connect at least one provider in AI Gateway before booting the runtime so the planner has a valid governed inference path.
  • Decide where the agent will run and what local command surface it truly needs before mounting Docker sockets, repos, or host paths.

Caminho rápido

Copy a working starter, run it in your environment, then come back here for the deeper rollout details.

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

Security agent Docker Compose bundle

Creates `deploy/security-agent/` with a Compose file, a ready-to-edit `.env.security-agent`, and a clean example copy so the agent can bootstrap with the documented runtime settings.

deploy/security-agent/
bash
BLACKSHIELD_SECURITY_AGENT_IMAGE=public.ecr.aws/blackshield-security/security-agent:1.0.0 \
BLACKSHIELD_SITE_URL=https://blackshield.chaplau.com \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/security-agent-docker.sh)
cd deploy/security-agent
Descarregar fonte

Executar isto

Docker Compose bootstrap

yaml
# Bootstrap the local runtime bundle first
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/security-agent-docker.sh)

# Edit deploy/security-agent/.env.security-agent and replace BLACKSHIELD_API_KEY
cd deploy/security-agent
docker compose -f docker-compose.security-agent.yml up -d
docker compose -f docker-compose.security-agent.yml logs -f

One-shot runtime launch

bash
docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sagent_xxxx \
  -e SECURITY_AGENT_MODEL=gpt-4o-mini \
  -e SECURITY_AGENT_PROVIDER=openai \
  -e SECURITY_AGENT_MAX_STEPS=8 \
  -e SECURITY_AGENT_COMMAND_TIMEOUT_SECONDS=120 \
  -v /var/run/docker.sock:/var/run/docker.sock \
  -v "$(pwd):/workspace" \
  -w /workspace \
  public.ecr.aws/blackshield-security/security-agent:1.0.0

Assignment payload example

json
{
  "assignment_type": "security_review_support",
  "title": "Review internet-facing payment service",
  "instructions": "Summarize open control gaps and propose review answers with evidence.",
  "scope": {
    "review_id": "2c79f0df-42b8-4d7f-9d28-7a7f4c5d6b01"
  }
}

Entender e personalizar

Use the guided steps below when you want to tailor the rollout, validate ownership, or expand the deployment safely.

Passo 1

Create an installation and save the bootstrap key

Use the Agents console so the runtime gets a dedicated installation identity instead of reusing a human API key.

  • Open `/agents` and create a Security Agent installation for the target tenant or environment.
  • Copy the bootstrap key shown after installation creation and store it in your secret manager.
  • Review the effective policy profile, allowed providers, and assignment types before deployment.
  • Confirm AI Gateway already has at least one approved provider connection for the tenant.

Como é o sucesso

Confirm AI Gateway already has at least one approved provider connection for the tenant.

Open Agents · Requer login

Passo 2

Bootstrap the runtime in the target environment

Use the Docker Compose bundle for the fastest start, then mount only the local paths and executables the agent actually needs.

  • Use the source bundle on this page to create `deploy/security-agent/` with a compose file, a ready-to-edit `.env.security-agent`, and a clean `.example` reference copy.
  • Replace `BLACKSHIELD_API_KEY` in `.env.security-agent`, then tune `SECURITY_AGENT_MODEL`, `SECURITY_AGENT_MAX_STEPS`, and command timeout values only if needed.
  • Run the container with the minimum local filesystem or Docker socket access your workflow requires.
  • Keep the runtime close to the tenant assets it needs to inspect so read-only local commands stay low-latency and auditable.

Como é o sucesso

Keep the runtime close to the tenant assets it needs to inspect so read-only local commands stay low-latency and auditable.

Security Agent Runtime Reference

Passo 3

Queue a blue-team assignment and review approvals

Start with read-first work such as finding triage, remediation follow-up, or security review support, then approve only the actions you want executed.

  • Create an assignment in `/agents` for `finding_triage`, `remediation_followup`, or `security_review_support`.
  • Watch the run timeline, planner observations, and uploaded artifacts to confirm the agent has enough context.
  • Use the approval queue for any mutating local command or product-side remediation or review update.
  • Download the final report and fold it into your incident, remediation, or review workflow.

Como é o sucesso

Download the final report and fold it into your incident, remediation, or review workflow.

Open Agents · Requer login

Como é o sucesso

  • The agent claims an assignment from `/api/v1/security-agents/agent/assignments/claim` and starts a run successfully.
  • Planner events and artifacts appear in the Agents console for the run without exposing tenant provider secrets to the runtime.
  • A mutating action pauses for approval and resumes correctly after approval is granted.
Deploy the Security Agent | Documentação BlackShield