BLACKSHIELD

Public Guide

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. Audience: Security engineers, identity and access management teams, platform engineers. Typical setup time: 10 minutes.

quickstart

Use this if

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.

Audience
Security engineers, identity and access management teams, platform engineers
Typical time
10 minutes

Before You Begin

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

Fast path

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

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.6 \
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.6 \
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

Run This

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

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.6
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.6
              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 }

Understand and customize

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

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

What success looks like

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

All Deployment Guides

Helpful context

Google Workspace API Docs

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

What success looks like

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

Open API Keys · Sign-in required

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

What success looks like

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

Download source bundles

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

What success looks like

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

View Findings · Sign-in required

What success looks like

  • 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.
Deploy the SaaS Scanner | BlackShield Docs