Öffentlicher Leitfaden

Deploy the SaaS Scanner

Discover over-privileged OAuth grants, stale app access, and shadow AI tool sprawl across Google Workspace, Microsoft 365, and GitHub. Runs entirely inside your tenant boundary. Zielgruppe: Security engineers, identity and access management teams, platform engineers. Typische Einrichtungszeit: 10 minutes.

quickstart

Verwenden Sie dies, wenn

Discover over-privileged OAuth grants, stale app access, and shadow AI tool sprawl across Google Workspace, Microsoft 365, and GitHub. Runs entirely inside your tenant boundary.

Zielgruppe: Security engineers, identity and access management teams, platform engineersTypische Dauer: 10 minutes

Bevor Sie beginnen

  • Obtain a provider OAuth token: Google Workspace access token (ya29.*) or Microsoft Graph access token.
  • For GitHub AI discovery: create a GitHub PAT with read:org and read:packages scopes.
  • Create a separate ingestion API key for SaaS scanner in Settings → API Keys.

Schnellstart

Kopieren Sie ein Starter-Setup, führen Sie es in Ihrer Umgebung aus und kehren Sie für tiefergehende Details hierher zurück.

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 SaaS scanner source

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

deploy/aws-saas-scanner/
bash
BLACKSHIELD_SAAS_IMAGE=public.ecr.aws/blackshield-security/saas-scanner:1.0.11 \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/aws-saas-scanner.sh)
cd deploy/aws-saas-scanner
Download source

GCP SaaS scanner source

Creates the Terraform module under `deploy/gcp-saas-scanner/` and prefills the current platform API URL so the Cloud Run deployment commands on this page work unchanged.

deploy/gcp-saas-scanner/
bash
BLACKSHIELD_SAAS_IMAGE=public.ecr.aws/blackshield-security/saas-scanner:1.0.11 \
BLACKSHIELD_SITE_URL=https://blackshield.chaplau.com \
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
bash <(curl -fsSL https://blackshield.chaplau.com/source-bundles/gcp-saas-scanner.sh)
cd deploy/gcp-saas-scanner
Download source

Ausführen

Google Workspace — one-shot OAuth scan

bash
docker run --rm \
  -e BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
  -e BLACKSHIELD_API_KEY=sp_xxxx \
  -e SAAS_SCAN_MODE=oauth \
  -e SAAS_SCAN_PROVIDER=google_workspace \
  -e SAAS_COLLECTOR_STRATEGY=api \
  -e SAAS_ACCESS_TOKEN=ya29.xxxx \
  -e GOOGLE_CUSTOMER_ID=C0xxxxxxx \
  -e SCAN_INTERVAL_SECONDS=0 \
  public.ecr.aws/blackshield-security/saas-scanner:1.0.11

AWS Fargate deploy — Google Workspace

bash
cd deploy/aws-saas-scanner
pip install -r requirements.txt

# Store credentials (once)
aws secretsmanager create-secret \
  --name "blackshield/saas-scanner/google" \
  --secret-string '{
    "BLACKSHIELD_API_KEY": "sp_xxxx",
    "SAAS_ACCESS_TOKEN": "ya29.xxxx",
    "GOOGLE_CUSTOMER_ID": "C0xxxxxxx"
  }'

# Deploy Fargate task (scans every 6 hours)
python3.11 -m venv .venv
source .venv/bin/activate
python -m pip install -r requirements.txt

export BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com
export SCANNER_IMAGE_URI=public.ecr.aws/blackshield-security/saas-scanner:1.0.11
export SAAS_SCAN_PROVIDER=google_workspace
export SECRET_NAME=blackshield/saas-scanner/google

cdk bootstrap
cdk deploy BlackShieldSaasScanner-Google --require-approval never

GitHub AI asset discovery — Kubernetes CronJob

yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: blackshield-saas-github
  namespace: blackshield
spec:
  schedule: "0 3 * * *"
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: saas-scanner
              image: public.ecr.aws/blackshield-security/saas-scanner:1.0.11
              env:
                - { name: BLACKSHIELD_API_URL, value: "https://api.blackshield.chaplau.com" }
                - { name: SAAS_SCAN_MODE,          value: ai_assets }
                - { name: SAAS_SCAN_PROVIDER,      value: github_code }
                - { name: SAAS_COLLECTOR_STRATEGY, value: api }
                - { name: SCAN_INTERVAL_SECONDS,   value: "0" }
                - { name: GITHUB_ORG,              value: your-org }
                - name: BLACKSHIELD_API_KEY
                  valueFrom:
                    secretKeyRef: { name: blackshield-saas-scanner, key: api-key }
                - name: GITHUB_TOKEN
                  valueFrom:
                    secretKeyRef: { name: blackshield-saas-scanner, key: github-token }

Verstehen und anpassen

Nutzen Sie die folgenden Schritte, um den Rollout anzupassen, Verantwortlichkeiten zu prüfen und die Bereitstellung sicher zu erweitern.

1

Schritt 1

Acquire Provider Credentials

Generate the necessary access tokens from your target SaaS provider. The scanner requires read-only scopes to inspect user grants and installed apps.

  • Google Workspace: Generate an admin token with `admin.directory.user.security` and `admin.directory.user.readonly` scopes.
  • Microsoft 365: Register an Entra ID application and grant it `Application.Read.All` and `User.Read.All` permissions.
  • GitHub: Create a Personal Access Token (PAT) or GitHub App token with `read:org` and `repo` scopes.

Erfolgreicher Abschluss

GitHub: Create a Personal Access Token (PAT) or GitHub App token with `read:org` and `repo` scopes.

All Deployment Guides

Hilfreicher Kontext

Google Workspace API Docs
2

Schritt 2

Validate Locally via Docker

Before deploying the automated schedule, verify your credentials and network access by running a one-shot container locally.

  • Pull the latest `saas-scanner` image from the public ECR registry.
  • Inject the provider tokens and your BlackShield API key as environment variables.
  • Check the terminal output to ensure the scanner successfully authenticates and pushes at least one batch of findings.

Erfolgreicher Abschluss

Check the terminal output to ensure the scanner successfully authenticates and pushes at least one batch of findings.

Open API Keys · Anmeldung erforderlich
3

Schritt 3

Deploy via Infrastructure as Code

Automate the scan cadence (e.g., daily) by deploying the scanner as a scheduled task in AWS or GCP.

  • AWS Fargate: Use the CDK source bundle to deploy an EventBridge-scheduled ECS task. Store your credentials in AWS Secrets Manager.
  • GCP Cloud Run: Use the Terraform bundle to deploy a Cloud Scheduler job triggering a Cloud Run execution. Store your credentials in GCP Secret Manager.
  • Kubernetes: Apply a `CronJob` manifest to run the scanner on a schedule.

Erfolgreicher Abschluss

Kubernetes: Apply a `CronJob` manifest to run the scanner on a schedule.

Download source bundles
4

Schritt 4

Review OAuth and AI Findings

Check the platform dashboard to review the ingested SaaS inventory.

  • Navigate to the Findings view and filter by `scanner=saas`.
  • Look for findings flagged as `over_privileged`, `high_risk_scope`, or `stale_grant`.
  • For GitHub targets, review any newly discovered shadow AI/LLM dependencies.

Erfolgreicher Abschluss

For GitHub targets, review any newly discovered shadow AI/LLM dependencies.

View Findings · Anmeldung erforderlich

Erfolgreicher Abschluss

  • One-shot Docker run exits 0 and findings_ingested_total > 0 in the health response.
  • AWS CDK deploy outputs the ECS cluster and task definition when using the Fargate bundle.
  • Findings appear in the platform with scanner=saas and flagged as over_privileged or stale_grant.
  • Re-scanning does not create duplicate findings.

Weiter

Keep your rollout moving with the next recommended step.

Findings prüfen und priorisieren
Deploy the SaaS Scanner | BlackShield Docs