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: 10 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 engineersTypical time: 10 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.

Apenas para demonstração

Esta configuração foi concebida para facilitar a utilização. Para implementar clientes de scanner em escala, planeie a sua arquitetura de implementação adequadamente ou contacte-nos para obter as melhores práticas empresariais.

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

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

1

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

Como é o sucesso

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
2

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

Como é o sucesso

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

Open API Keys · Requer login
3

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

Como é o sucesso

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

Download source bundles
4

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

Como é o sucesso

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

View Findings · Requer login

Como é o sucesso

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

Continuar

Keep your rollout moving with the next recommended step.

Rever e priorizar achados
Deploy the SaaS Scanner | Documentação BlackShield