BLACKSHIELD

Public Guide

Deploy the Cloud Scanner on AWS

Scan your AWS environment for misconfigurations with Prowler, deployed as a Lambda container on EventBridge Scheduler — no EC2, no always-on compute. Audience: Cloud engineers, security engineers, platform teams. Typical setup time: 5 minutes.

quickstart

Use this if

Scan your AWS environment for misconfigurations with Prowler, deployed as a Lambda container on EventBridge Scheduler — no EC2, no always-on compute.

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

Before You Begin

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

Fast path

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

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 Lambda deployment commands on this page work unchanged.

deploy/aws-cloud-scanner/
bash
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-cloud-scanner.sh)
cd deploy/aws-cloud-scanner
Download source

Run This

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
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)
cdk bootstrap

# 3. Deploy — Lambda runs Prowler every 6 hours
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
SCANNER_IMAGE_URI=public.ecr.aws/blackshield-security/cloud-scanner:1.0.0 \
cdk deploy --require-approval never

Trigger manual scan + tail logs

bash
# Invoke Lambda manually
aws lambda invoke \
  --function-name BlackShieldCloudScanner \
  --invocation-type Event \
  /tmp/response.json

# Follow execution logs in real time
aws logs tail /aws/lambda/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

Understand and customize

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

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

What success looks like

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

Open API Keys · Sign-in required

Step 2

Deploy the CDK stack

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

  • Bootstrap the local source bundle first, then run cd deploy/aws-cloud-scanner && pip install -r requirements.txt
  • Set BLACKSHIELD_API_URL and SCANNER_IMAGE_URI environment variables.
  • Run: cdk deploy --require-approval never
  • The stack creates a 3 GB Lambda, IAM role with SecurityAudit + ViewOnlyAccess, and an EventBridge schedule.

What success looks like

The stack creates a 3 GB Lambda, IAM role with SecurityAudit + ViewOnlyAccess, and an EventBridge schedule.

All Deployment Guides

Step 3

Verify and scale to multiple accounts

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

  • Trigger manually: aws lambda invoke --function-name BlackShieldCloudScanner --invocation-type Event /tmp/out.json
  • Tail logs: aws logs tail /aws/lambda/BlackShieldCloudScanner --follow
  • Confirm findings appear in the platform with scanner=cloud.
  • For multi-account: use CloudFormation StackSets targeting your OU — see the Developer Guide.

What success looks like

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

View Findings · Sign-in required

What success looks like

  • cdk deploy completes without errors and outputs the Lambda function ARN.
  • Manual Lambda invocation succeeds: aws lambda invoke --function-name BlackShieldCloudScanner --invocation-type Event /tmp/out.json
  • Cloud posture findings appear in the platform Findings view within 15 minutes.
Deploy the Cloud Scanner on AWS | BlackShield Docs