BLACKSHIELD

Guia público

Deploy the Cloud Scanner on AWS

Scan your AWS environment for misconfigurations with Prowler, deployed as a scheduled ECS Fargate task — no EC2, no always-on compute. Público: Cloud engineers, security engineers, platform teams. Tempo típico de configuração: 5 minutes.

quickstart

Use isto se

Scan your AWS environment for misconfigurations with Prowler, deployed as a scheduled ECS Fargate task — no EC2, no always-on compute.

Audience
Cloud engineers, security engineers, platform teams
Typical time
5 minutes

Antes de começar

  • Install AWS CDK v2: npm install -g aws-cdk@latest (requires Node.js 22 or 24).
  • Ensure AWS CLI is configured with credentials for the target account.
  • Create an ingestion API key in Settings → API Keys with Ingestion scope.

Caminho rápido

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

Apenas para demonstração

Esta configuração foi concebida para facilitar a utilização. Para implementar clientes de scanner em escala, planeie a sua arquitetura de implementação adequadamente ou contacte-nos para obter as melhores práticas empresariais.

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.

AWS cloud scanner source

Creates the AWS CDK project under `deploy/aws-cloud-scanner/` so the scheduled Fargate deployment commands on this page work unchanged.

deploy/aws-cloud-scanner/
bash
BLACKSHIELD_CLOUD_IMAGE=public.ecr.aws/blackshield-security/cloud-scanner:1.0.6 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-cloud-scanner.sh)
cd deploy/aws-cloud-scanner
Descarregar fonte

Executar isto

Store API key + deploy (three commands)

bash
# Bootstrap the local source bundle first
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-cloud-scanner.sh)

cd deploy/aws-cloud-scanner

# Create a Python 3.11 virtual environment
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

# 1. Store API key (once per account)
aws secretsmanager create-secret \
  --name "blackshield/cloud-scanner/api-key" \
  --secret-string "sp_xxxx"

# 2. Bootstrap CDK (once per account+region)
# Export required env vars before bootstrap and deploy
export BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
export SCANNER_IMAGE_URI=public.ecr.aws/blackshield-security/cloud-scanner:1.0.6
cdk bootstrap

# 3. Deploy — Fargate runs Prowler every 6 hours
cdk deploy --require-approval never

Trigger manual scan + tail logs

bash
# Read stack outputs for a one-off ECS task run
STACK_NAME=BlackShieldCloudScanner
CLUSTER_NAME=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
  --query "Stacks[0].Outputs[?OutputKey=='ClusterName'].OutputValue" --output text)
TASK_DEFINITION_ARN=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
  --query "Stacks[0].Outputs[?OutputKey=='TaskDefinitionArn'].OutputValue" --output text)
SUBNET_IDS=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
  --query "Stacks[0].Outputs[?OutputKey=='SubnetIds'].OutputValue" --output text)
SECURITY_GROUP_ID=$(aws cloudformation describe-stacks --stack-name "$STACK_NAME" \
  --query "Stacks[0].Outputs[?OutputKey=='SecurityGroupId'].OutputValue" --output text)

aws ecs run-task \
  --cluster "$CLUSTER_NAME" \
  --launch-type FARGATE \
  --task-definition "$TASK_DEFINITION_ARN" \
  --network-configuration "awsvpcConfiguration={subnets=[$SUBNET_IDS],securityGroups=[$SECURITY_GROUP_ID],assignPublicIp=DISABLED}"

# Follow execution logs in real time
aws logs tail /aws/ecs/BlackShieldCloudScanner --follow

# Check findings arrived
curl -sf \
  -H "X-API-Key: sp_xxxx" \
  "https://api.blackshield.chaplau.com/api/v1/findings?scanner=cloud&limit=5" \
  | python3 -m json.tool

Entender e personalizar

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

Passo 1

Prerequisites and API key

Install the CDK, store your API key in Secrets Manager, and bootstrap the target account.

  • Install AWS CDK v2: npm install -g aws-cdk@latest (requires Node.js 22 or 24).
  • Create an Ingestion API key in Settings → API Keys.
  • Store it: aws secretsmanager create-secret --name blackshield/cloud-scanner/api-key --secret-string sp_xxxx
  • Bootstrap the account+region: cdk bootstrap (once per account/region).

Como é o sucesso

Bootstrap the account+region: cdk bootstrap (once per account/region).

Open API Keys · Requer login

Passo 2

Deploy the CDK stack

Three commands deploy Fargate + EventBridge + IAM + CloudWatch logging.

  • Bootstrap the local source bundle first, then run cd deploy/aws-cloud-scanner
  • Create a Python 3.11 venv: python3.11 -m venv .venv && source .venv/bin/activate && python -m pip install -r requirements.txt
  • Export BLACKSHIELD_API_URL and SCANNER_IMAGE_URI environment variables.
  • Run: cdk bootstrap && cdk deploy --require-approval never
  • The stack creates a one-shot Fargate task in private subnets, IAM role with SecurityAudit + ViewOnlyAccess, and an EventBridge schedule.

Como é o sucesso

The stack creates a one-shot Fargate task in private subnets, IAM role with SecurityAudit + ViewOnlyAccess, and an EventBridge schedule.

Scanner Licensing Defaults

Passo 3

Verify and scale to multiple accounts

Trigger a manual run, confirm findings, then roll out to the entire AWS Organization.

  • Trigger manually with aws ecs run-task using the CloudFormation outputs.
  • Tail logs: aws logs tail /aws/ecs/BlackShieldCloudScanner --follow
  • Confirm findings appear in the platform with scanner=cloud.
  • For multi-account: use CloudFormation StackSets targeting your OU — see the Developer Guide.

Como é o sucesso

For multi-account: use CloudFormation StackSets targeting your OU — see the Developer Guide.

View Findings · Requer login

Como é o sucesso

  • cdk deploy completes without errors and outputs the ECS cluster and task definition.
  • Manual ECS task run succeeds using the CloudFormation outputs.
  • Cloud posture findings appear in the platform Findings view within 15 minutes.
Deploy the Cloud Scanner on AWS | Documentação BlackShield