BLACKSHIELD

Guia público

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. Público: Security engineers, identity and access management teams, platform engineers. Tempo típico de configuração: 5 minutes.

Antes de começar

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

Passo a passo

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

Passo 2

Store credentials and deploy

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

  • Google Workspace — store in Secrets Manager: { SECPLATFORM_API_KEY, SAAS_ACCESS_TOKEN, GOOGLE_CUSTOMER_ID }
  • Microsoft 365 — store in Secrets Manager: { SECPLATFORM_API_KEY, SAAS_ACCESS_TOKEN }
  • GitHub — store GITHUB_TOKEN and SECPLATFORM_API_KEY as Kubernetes Secrets or Secrets Manager entries.
  • AWS Lambda deploy: SAAS_SCAN_PROVIDER=google_workspace SECRET_NAME=secplatform/saas-scanner/google cdk deploy --require-approval never
  • GCP Cloud Run deploy: TF_VAR_saas_scan_provider=google_workspace terraform apply -auto-approve

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

Obtém o bundle de código fonte

Descarrega os ficheiros exatos usados neste guia ou executa o instalador de um só comando para os escrever localmente antes do deploy.

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://stg-blackshield.chaplau.com/source-bundles/aws-saas-scanner.sh)
cd deploy/aws-saas-scanner
Descarregar fonte

GCP SaaS scanner source

Creates the Terraform module under `deploy/gcp-saas-scanner/` so the Cloud Run deployment commands on this page work unchanged.

deploy/gcp-saas-scanner/
bash
bash <(curl -fsSL https://stg-blackshield.chaplau.com/source-bundles/gcp-saas-scanner.sh)
cd deploy/gcp-saas-scanner
Descarregar fonte

Executar isto

Google Workspace — one-shot OAuth scan

bash
docker run --rm \
  -e SECPLATFORM_API_URL=https://api.yourdomain.com \
  -e SECPLATFORM_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 \
  ghcr.io/your-org/secplatform-saas-scanner:latest

AWS Lambda deploy — Google Workspace

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

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

# Deploy Lambda (scans every 6 hours)
SECPLATFORM_API_URL=https://api.yourdomain.com \
SCANNER_IMAGE_URI=ghcr.io/your-org/secplatform-saas-scanner:1.0.0 \
SAAS_SCAN_PROVIDER=google_workspace \
SECRET_NAME=secplatform/saas-scanner/google \
cdk deploy SecPlatformSaasScanner-Google --require-approval never

GitHub AI asset discovery — Kubernetes CronJob

yaml
apiVersion: batch/v1
kind: CronJob
metadata:
  name: secplatform-saas-github
  namespace: secplatform
spec:
  schedule: "0 3 * * *"
  concurrencyPolicy: Forbid
  jobTemplate:
    spec:
      template:
        spec:
          restartPolicy: OnFailure
          containers:
            - name: saas-scanner
              image: ghcr.io/your-org/secplatform-saas-scanner:1.0.0
              env:
                - { name: SECPLATFORM_API_URL, value: "https://api.yourdomain.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: SECPLATFORM_API_KEY
                  valueFrom:
                    secretKeyRef: { name: secplatform-saas-scanner, key: api-key }
                - name: GITHUB_TOKEN
                  valueFrom:
                    secretKeyRef: { name: secplatform-saas-scanner, key: github-token }

Verificações de sucesso

  • 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 | Documentação BlackShield