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.

quickstart

Use isto se

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

Caminho rápido

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

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://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/` 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
Descarregar fonte

Executar isto

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 e personalizar

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

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.

Como é o sucesso

Kubernetes: CronJob manifest in the Developer Guide.

All Deployment Guides

Passo 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

Como é o sucesso

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 · Requer login

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.

Como é o sucesso

Schedule scans at least daily to catch new grant additions.

View Findings · Requer login

Como é o 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