دليل عام

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. الجمهور: Cloud engineers, security engineers, platform teams. وقت الإعداد المعتاد: 5 minutes.

quickstart

استخدم هذا إذا

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

الجمهور المستهدف: Cloud engineers, security engineers, platform teamsالوقت النموذجي: 5 minutes

قبل البدء

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

المسار السريع

انسخ إعداد البداية وقم بتشغيله في بيئتك، ثم عد إلى هنا للحصول على تفاصيل التوزيع الأكثر عمقًا.

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

نفّذ هذا

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

الفهم والتخصيص

استخدم الخطوات الإرشادية أدناه عندما ترغب في تخصيص التوزيع أو التحقق من الملكية أو توسيع النشر بأمان.

1

الخطوة 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).

معايير النجاح

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

Open API Keys · تسجيل الدخول مطلوب
2

الخطوة 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.

معايير النجاح

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

Scanner Licensing Defaults
3

الخطوة 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.

معايير النجاح

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

View Findings · تسجيل الدخول مطلوب

معايير النجاح

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

المتابعة

Keep your rollout moving with the next recommended step.

استيعاب أولى النتائج
Deploy the Cloud Scanner on AWS | BlackShield Docs