Public Guide

Guided Scanner and Appliance Onboarding

Use the dashboard wizard to choose a scanner or defense-in-depth appliance, create the right scoped API key, and copy one command that handles BlackShield setup for you. Audience: Tenant admins, operations teams, platform engineers, and customer-success teams helping a tenant onboard. Typical setup time: 5-10 minutes.

Start herejourney

Use this if

Use the dashboard wizard to choose a scanner or defense-in-depth appliance, create the right scoped API key, and copy one command that handles BlackShield setup for you.

Audience: Tenant admins, operations teams, platform engineers, and customer-success teams helping a tenant onboardTypical time: 5-10 minutes

Start here

Step 3 of 7

Recommended
1
2
3
4
5
6
7

Before You Begin

  • Confirm you can sign in to the tenant workspace.
  • Use a tenant role with API key write permissions.
  • Know whether you are installing a scanner runtime or a defense-in-depth appliance.

Do this now

1

Step 1

Open the install wizard

The wizard keeps runtime selection, provider/deployment choices, scoped API key creation, and command generation in one dashboard workflow.

  • Open `/onboarding/install` from the dashboard navigation or from the API Keys page.
  • Use an account with API key write permissions for the tenant.
  • Choose Scanner for pipeline, cloud, Kubernetes, VM, SaaS, or network sensor runtimes.
  • Choose Appliance for defense-in-depth enforcement appliances.

What success looks like

You are ready to configure a scanner or appliance without switching between docs, API keys, and runtime-specific setup pages.

Open Install Wizard
2

Step 2

Choose the runtime and expiry

The wizard maps each runtime to least-privilege API key scopes and stable public image tags.

  • Use the 90 day default expiry, or select 30, 60, 90, or 365 days before generation.
  • For pipeline scanners, select GitHub Actions, GitLab CI, or Bitbucket Pipelines and choose the scanner tools to enable.
  • For cloud, Kubernetes, VM, SaaS, network, and appliance runtimes, select the deployment target instead of copying low-level container flags.
  • Finding scanners receive `ingest:findings`; network sensors receive `ingest:siem`.
  • SaaS scanners receive `ingest:external_assets` and `ingest:external_findings`.
  • Appliances receive `ingest:appliances`, `ingest:connectors`, and `appliances:read`.

What success looks like

The selected runtime has a bounded expiry and least-privilege scope mapping.

Review API Keys
3

Step 3

Generate and copy the command

Generation creates a one-time raw API key and inserts it into a shell-safe command for the selected runtime.

  • Click Generate installation only when you are ready to copy the command.
  • Copy the full command and run it in the repository, host, cloud, or cluster administration environment shown by the selected bundle.
  • Let the command configure BlackShield API keys, source files, and provider variables where the selected runtime supports it.
  • Revoke and regenerate the key if the command is pasted into chat, tickets, logs, or shell history.

What success looks like

The runtime has a copy-paste command that includes the one-time API key and pinned image tag.

Review Scanner Defaults

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.

Run This

Example generated pipeline scanner command
export BLACKSHIELD_PIPELINE_IMAGE='public.ecr.aws/blackshield-security/pipeline-scanner:1.0.9'
export BLACKSHIELD_API_URL='https://api.blackshield.chaplau.com'
export BLACKSHIELD_API_KEY='paste-generated-key-here'
export BLACKSHIELD_PIPELINE_TOOLS='trivy,trufflehog,syft'
export BLACKSHIELD_REPO_CHANGE_MODE='create_branch_commit'
bash <(curl -fsSL 'https://blackshield.chaplau.com/source-bundles/github-security-scan.sh')

What success looks like

  • The command includes `BLACKSHIELD_API_URL` and `BLACKSHIELD_API_KEY`.
  • The API key scopes match the selected runtime.
  • The copied command uses a managed source bundle and stable public image tag.

Continue

Keep your rollout moving with the next recommended step.

Deploy the Pipeline Scanner
Guided Scanner and Appliance Onboarding | BlackShield Docs