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: 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 engineers
Typical 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.6 \
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.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
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.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 e personalizar

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

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

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

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

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.
Deploy the SaaS Scanner | Documentação BlackShield