सार्वजनिक गाइड

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. लक्षित पाठक: Security engineers, platform engineers, and security operations teams. सामान्य सेटअप समय: 5 minutes.

quickstart

इसका उपयोग करें यदि

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.

लक्षित दर्शक: Security engineers, platform engineers, and security operations teamsविशिष्ट समय: 5 minutes

शुरू करने से पहले

  • 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.

त्वरित मार्ग

एक प्रारंभिक सेटअप कॉपी करें, इसे अपने परिवेश में चलाएं, फिर गहन रोलआउट विवरण के लिए यहां वापस आएं।

Demonstration only

This configuration is designed for ease of use. To deploy scanner clients at scale, please plan your deployment architecture accordingly or contact us for enterprise best practices.

Get the source bundle

Download the exact source files referenced on this page, or run the one-command installer to write them locally before following the deployment steps.

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.2.7 \
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
Download source

यह चलाएँ

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

Least-privilege Linux runtime launch

bash
SECURITY_AGENT_IMAGE=public.ecr.aws/blackshield-security/security-agent:1.2.7
SECURITY_AGENT_HEALTH_PORT="$(docker run --rm --network host --entrypoint python "$SECURITY_AGENT_IMAGE" -c "import socket; s=socket.socket(); s.bind(('127.0.0.1',0)); print(s.getsockname()[1]); s.close()")" && \
docker run -d --name blackshield-security-agent --restart unless-stopped \
  --network host --read-only --user 0:0 --cap-drop ALL --cap-add DAC_OVERRIDE --security-opt no-new-privileges \
  --health-cmd='python -c "import os,urllib.request,sys; p=os.environ[\"SECURITY_AGENT_HEALTH_PORT\"]; r=urllib.request.urlopen(f\"http://127.0.0.1:{p}/health\",timeout=3); sys.exit(0 if r.status==200 else 1)"' \
  --tmpfs /tmp:rw,noexec,nosuid,size=256m \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sagent_xxxx \
  -e SECURITY_AGENT_MAX_STEPS=8 \
  -e SECURITY_AGENT_HEALTH_HOST=127.0.0.1 \
  -e SECURITY_AGENT_HEALTH_PORT="$SECURITY_AGENT_HEALTH_PORT" \
  -e SECURITY_AGENT_MAX_CAPABILITY_TIMEOUT_SECONDS=1800 \
  -v /:/host:ro \
  -v blackshield-agent-state:/var/lib/blackshield-agent \
  "$SECURITY_AGENT_IMAGE"

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"
  }
}

समझें और कस्टमाइज़ करें

जब आप रोलआउट को अनुकूलित करना चाहते हैं, स्वामित्व को मान्य करना चाहते हैं या परिनियोजन का सुरक्षित रूप से विस्तार करना चाहते हैं, तो नीचे दिए गए चरणों का उपयोग करें।

1

चरण 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.

सफलता कैसी दिखती है

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

Open Agents · साइन-इन आवश्यक
2

चरण 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`; AI Gateway governs provider and model while managed capability deadlines and the loopback health bind remain safe runtime defaults.
  • Use host networking, container UID 0 with only `DAC_OVERRIDE`, and the read-only `/host` mount for complete host assessment; do not mount the Docker socket.
  • Confirm `/agents` reports the expected `host_assessment` and `web_assessment` capabilities before queueing work.

सफलता कैसी दिखती है

Confirm `/agents` reports the expected `host_assessment` and `web_assessment` capabilities before queueing work.

Security Agent Runtime Reference
3

चरण 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 review, host assessment, a scoped web assessment, remediation follow-up, or security review support.
  • Watch the resumable step timeline, findings created, 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.

सफलता कैसी दिखती है

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

Open Agents · साइन-इन आवश्यक

सफलता कैसी दिखती है

  • 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.

जारी रखें

Keep your rollout moving with the next recommended step.

फाइंडिंग्स की समीक्षा करें और प्राथमिकता तय करें
Deploy the Security Agent | BlackShield Docs