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

Solo demostración

Esta configuración está diseñada para facilitar el uso. Para desplegar clientes de escaneo a escala, planifique su arquitectura de despliegue en consecuencia o contáctenos para obtener las mejores prácticas empresariales.

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

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

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.

Cómo se ve el éxito

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

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

Cómo se ve el éxito

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

Open API Keys · Requiere inicio de sesión

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

Cómo se ve el éxito

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

Download source bundles

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

Cómo se ve el éxito

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

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.
  • 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.
Deploy the SaaS Scanner | Docs de BlackShield