Guide public

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. Audience: Cloud engineers, security engineers, platform teams. Temps moyen de mise en place: 5 minutes.

quickstart

Utilisez ceci si

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

Public visé: Cloud engineers, security engineers, platform teamsDurée estimée: 5 minutes

Avant de commencer

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

Parcours rapide

Copiez une configuration de démarrage, exécutez-la dans votre environnement, puis revenez ici pour les détails avancés.

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.

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.12 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-cloud-scanner.sh)
cd deploy/aws-cloud-scanner
Download source

Exécuter

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

Comprendre et personnaliser

Suivez les étapes ci-dessous pour adapter le déploiement, vérifier les accès et étendre l'infrastructure en toute sécurité.

1

Étape 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).

Critères de réussite

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

Open API Keys · Connexion requise
2

Étape 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.

Critères de réussite

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

Scanner Licensing Defaults
3

Étape 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.

Critères de réussite

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

View Findings · Connexion requise

Critères de réussite

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

Continuer

Keep your rollout moving with the next recommended step.

Ingérer vos premières détections
Deploy the Cloud Scanner on AWS | BlackShield Docs