BLACKSHIELD

Guía pública

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. Audiencia: Security engineers, identity and access management teams, platform engineers. Tiempo típico de configuración: 5 minutes.

quickstart

Úsalo si

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

Antes de comenzar

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

Camino rápido

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

Obtén el bundle de código fuente

Descarga los archivos exactos usados en esta guía o ejecuta el instalador de un solo comando para escribirlos localmente antes del despliegue.

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
Descargar fuente

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
Descargar fuente

Ejecuta esto

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 }

Entender y personalizar

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

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

Cómo se ve el éxito

Kubernetes: CronJob manifest in the Developer Guide.

All Deployment Guides

Paso 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

Cómo se ve el éxito

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 · Requiere inicio de sesión

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

Cómo se ve el éxito

Schedule scans at least daily to catch new grant additions.

View Findings · Requiere inicio de sesión

Cómo se ve el éxito

  • 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 | Docs de BlackShield