BLACKSHIELD

公開ガイド

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. 対象: Security engineers, identity and access management teams, platform engineers. 一般的な設定時間: 5 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
5 minutes

開始前に

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

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

deploy/aws-saas-scanner/
bash
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.0 \
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

実行する

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

AWS Lambda 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 Lambda (scans every 6 hours)
BLACKSHIELD_API_URL=https://api.blackshield.chaplau.com \
SCANNER_IMAGE_URI=public.ecr.aws/blackshield-security/saas-scanner:1.0.0 \
SAAS_SCAN_PROVIDER=google_workspace \
SECRET_NAME=blackshield/saas-scanner/google \
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.0
              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.

ステップ 1

Choose your provider and runtime

Pick the SaaS provider to scan and the cloud runtime that fits your environment.

  • OAuth inventory: google_workspace (Google Workspace) or microsoft_graph (Microsoft 365).
  • AI asset discovery: github_code (scans GitHub org for AI/LLM package sprawl).
  • AWS runtime: Lambda + EventBridge — use deploy/aws-saas-scanner/ CDK stack.
  • GCP runtime: Cloud Run Job + Cloud Scheduler — use deploy/gcp-saas-scanner/ Terraform module.
  • Kubernetes: CronJob manifest in the Developer Guide.

What success looks like

Kubernetes: CronJob manifest in the Developer Guide.

All Deployment Guides

ステップ 2

Store credentials and deploy

Store provider tokens securely, then deploy with one CDK or Terraform command.

  • Google Workspace — store in Secrets Manager: { BLACKSHIELD_API_KEY, SAAS_ACCESS_TOKEN, GOOGLE_CUSTOMER_ID }
  • Microsoft 365 — store in Secrets Manager: { BLACKSHIELD_API_KEY, SAAS_ACCESS_TOKEN }
  • GitHub — store GITHUB_TOKEN and BLACKSHIELD_API_KEY as Kubernetes Secrets or Secrets Manager entries.
  • AWS Lambda deploy: SAAS_SCAN_PROVIDER=google_workspace SECRET_NAME=blackshield/saas-scanner/google cdk deploy --require-approval never
  • GCP Cloud Run deploy: bootstrap the source bundle first so `deploy/gcp-saas-scanner/` is created with `BLACKSHIELD_API_URL` prefilled, then run TF_VAR_saas_scan_provider=google_workspace terraform apply -auto-approve

What success looks like

GCP Cloud Run deploy: bootstrap the source bundle first so `deploy/gcp-saas-scanner/` is created with `BLACKSHIELD_API_URL` prefilled, then run TF_VAR_saas_scan_provider=google_workspace terraform apply -auto-approve

Open API Keys · Sign-in required

ステップ 3

Validate OAuth findings

Confirm grant inventory is flowing and review over-privileged apps immediately.

  • Run a one-shot Docker command first to validate before deploying: docker run --rm -e SAAS_SCAN_MODE=oauth -e SAAS_SCAN_PROVIDER=google_workspace ...
  • Open the platform and filter Findings by scanner=saas to see OAuth grant inventory.
  • Review findings flagged as over_privileged, high_risk_scope, or stale_grant — these need immediate attention.
  • Schedule scans at least daily to catch new grant additions.

What success looks like

Schedule scans at least daily to catch new grant additions.

View Findings · Sign-in required

What success looks like

  • One-shot Docker run exits 0 and findings_ingested_total > 0 in the health response.
  • 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