What your infrastructure looks like.

Connect this workspace

Under Shield → Posture, pick TillDev and connect. The first sync starts at once and usually takes seconds. From the CLI:

tilldev shield posture add till --wait                       # read this workspace first
tilldev shield posture                                       # every connector and its state
tilldev shield posture show <connector-id>                   # recent syncs, and the identity to trust
tilldev shield posture sync <connector-id> --wait            # exits 1 when the sync fails
tilldev shield posture schedule <connector-id> hourly        # or daily, or off
tilldev shield posture resources --type till.forge_repo      # the inventory, 100 a page
tilldev shield posture resources show <resource-id>          # the settings last read
tilldev shield posture rm <connector-id>                     # asks first; --yes in scripts

The TillDev connector reads these, and nothing else:

How each provider is reached

For a cloud account, TillDev signs a token that lasts five minutes, naming the connector as its subject, and the account exchanges it for read-only access through its own identity federation. You trust two values in the account: the issuer, https://tilldev.dev/oidc/connectors, and the subject the connector shows, workspace:<workspace-id>:connector:<connector-id>. Pin the subject, not only the issuer, so no other workspace’s connector can use the trust. The issuer publishes its discovery document at /oidc/connectors/.well-known/openid-configuration and its public keys at /oidc/connectors/jwks.json. Remove the trust in the account and the next sync can’t read.

A provider without federation keeps a read-only token. It is sealed with your workspace’s own key in TillSecrets, unsealed only for a sync that is running, and never returned by the API: you see its last four characters. Replace it any time; disconnecting destroys it. Every time a sync is given a token or a federation token is signed for it, TillSecrets records it in the audit log.

Connect an AWS account

An AWS connector holds no AWS key. Each sync assumes a role in your account for fifteen minutes, using a token TillDev signs for that connector alone. Adding the connector starts no sync: first the account has to trust it, in three steps, and Shield → Posture shows them with your account and connector filled in.

1. In IAM, add an OpenID Connect identity provider with the URL https://tilldev.dev/oidc/connectors and the audience sts.amazonaws.com. One provider serves every connector in the account.
2. Create a role, TillDevPosture unless you name another, with the trust policy below. It names this connector’s subject, so no other workspace and no other connector can assume it.
3. Give the role the read policy below. It allows exactly the 21 calls a sync makes, all of them reads. The AWS managed SecurityAudit policy works too, and allows more.

tilldev shield posture add aws --account 123456789012       # --role and --regions are optional
tilldev shield posture trust <connector-id> --out .          # writes trust.json and read.json
aws iam create-open-id-connect-provider --url https://tilldev.dev/oidc/connectors --client-id-list sts.amazonaws.com
aws iam create-role --role-name TillDevPosture --assume-role-policy-document file://trust.json
aws iam put-role-policy --role-name TillDevPosture --policy-name TillDevPostureRead --policy-document file://read.json
tilldev shield posture sync <connector-id> --wait

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::123456789012:oidc-provider/tilldev.dev/oidc/connectors"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "tilldev.dev/oidc/connectors:aud": "sts.amazonaws.com",
          "tilldev.dev/oidc/connectors:sub": "workspace:<workspace-id>:connector:<connector-id>"
        }
      }
    }
  ]
}

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Action": [
        "cloudtrail:DescribeTrails",
        "cloudtrail:GetTrailStatus",
        "ec2:DescribeInstances",
        "ec2:DescribeRegions",
        "ec2:DescribeSecurityGroups",
        "ec2:GetEbsEncryptionByDefault",
        "iam:GenerateCredentialReport",
        "iam:GetAccountPasswordPolicy",
        "iam:GetAccountSummary",
        "iam:GetCredentialReport",
        "iam:ListRoles",
        "rds:DescribeDBInstances",
        "s3:GetAccountPublicAccessBlock",
        "s3:GetBucketLocation",
        "s3:GetBucketLogging",
        "s3:GetBucketOwnershipControls",
        "s3:GetBucketPolicyStatus",
        "s3:GetBucketPublicAccessBlock",
        "s3:GetBucketVersioning",
        "s3:GetEncryptionConfiguration",
        "s3:ListAllMyBuckets"
      ],
      "Resource": "*"
    }
  ]
}

A sync reads every region enabled for the account unless the connector lists the regions to read. A region the role can’t read, for example because a service control policy blocks it, leaves the regional types partial and names the region; list only the regions you use and the next sync reads in full. A sync makes at most 10,000 AWS calls and retries when AWS slows it down. Only the commercial AWS partition can be connected; China and GovCloud can’t yet.

A setting the role isn’t allowed to read is listed under unread on that resource rather than guessed. When a sync can’t start a session it fails and says why: the account doesn’t trust the issuer yet, the role is missing or its trust policy names another connector, or the audience is wrong.

Connect a Google Cloud project

A Google Cloud connector holds no service account key. Each sync exchanges a token TillDev signs for that connector at Google’s security token service, through a workload identity pool you control, and reads with an access token that lasts 15 minutes. Adding the connector starts no sync: first the project has to trust it, and Shield → Posture shows the steps with your project and connector filled in.

1. Choose the pool and provider names, and add the connector with the provider’s full name, starting //iam.googleapis.com/, as its audience. The connector then shows its subject.
2. Create the workload identity pool and an OpenID Connect provider in it with the issuer https://tilldev.dev/oidc/connectors, the attribute mapping google.subject=assertion.sub, the allowed audiences left empty, and the attribute condition assertion.sub == '<subject>'. The condition names this connector, so no other workspace and no other connector can use the provider.
3. Grant the connector’s principal read access on the project: a custom role with the 9 permissions a sync uses, all of them reads, or the predefined Security Reviewer and Viewer roles, which allow more.

tilldev shield posture add gcp --account my-project-123 --audience //iam.googleapis.com/projects/123456/locations/global/workloadIdentityPools/tilldev/providers/tilldev
tilldev shield posture trust <connector-id>                  # the subject, principal and commands, filled in
gcloud iam workload-identity-pools create tilldev --project=123456 --location=global
gcloud iam workload-identity-pools providers create-oidc tilldev --project=123456 --location=global \
  --workload-identity-pool=tilldev --issuer-uri=https://tilldev.dev/oidc/connectors \
  --attribute-mapping=google.subject=assertion.sub --attribute-condition="assertion.sub == 'workspace:<workspace-id>:connector:<connector-id>'"
gcloud iam roles create tillDevPostureRead --project=my-project-123 --title="TillDev posture read" \
  --permissions=cloudsql.instances.list,compute.firewalls.list,compute.instances.list,iam.serviceAccountKeys.list,iam.serviceAccounts.list,resourcemanager.projects.get,resourcemanager.projects.getIamPolicy,storage.buckets.getIamPolicy,storage.buckets.list
gcloud projects add-iam-policy-binding my-project-123 --role=projects/my-project-123/roles/tillDevPostureRead \
  --member="principal://iam.googleapis.com/projects/123456/locations/global/workloadIdentityPools/tilldev/subject/workspace:<workspace-id>:connector:<connector-id>"
tilldev shield posture sync <connector-id> --wait

To read as a service account instead, name it on the connector, grant it the read role, and grant the connector’s principal Workload Identity User on that service account. The IAM Service Account Credentials API must be on in the project that owns it. An API that is off in the project, such as Cloud SQL, leaves its type empty and is listed on the project rather than failing the sync. A zone Google Cloud can’t reach leaves instances partial and names it. A sync makes at most 10,000 Google Cloud calls.

When the exchange is refused the sync fails and says why: the pool or provider doesn’t exist or is disabled, the attribute condition names another connector, the provider limits its audiences, or its issuer isn’t TillDev’s.

Connect an Azure subscription

An Azure connector holds no client secret. Each sync signs in to Microsoft Entra ID as an app registration in your tenant, using a token TillDev signs for that connector alone as the app’s federated credential, and reads with the Reader role. Adding the connector starts no sync: first the app has to trust it, and Shield → Posture shows the steps with your tenant, app and subscription filled in.

1. Register an app in your tenant, or use one you have, and make sure it has a service principal. One app can serve every connector; add the connector with the tenant ID and the app’s client ID.
2. Add a federated credential to the app with the issuer https://tilldev.dev/oidc/connectors, the audience api://AzureADTokenExchange and the subject the connector shows. The subject names this connector, so no other workspace can sign in as the app.
3. Assign the app the built-in Reader role on the subscription. Reader reads settings and never the data in storage, databases or vaults.

az login --tenant <tenant-id>
az ad app create --display-name "TillDev posture"            # note its appId, the client ID
az ad sp create --id <client-id>
tilldev shield posture add azure --account 00000000-0000-0000-0000-000000000000 --tenant-id <tenant-id> --client-id <client-id>
tilldev shield posture trust <connector-id> --out .          # writes credential.json
az ad app federated-credential create --id <client-id> --parameters credential.json
az role assignment create --assignee <client-id> --role Reader --scope /subscriptions/00000000-0000-0000-0000-000000000000
tilldev shield posture sync <connector-id> --wait

{
  "name": "tilldev-<connector-id>",
  "issuer": "https://tilldev.dev/oidc/connectors",
  "subject": "workspace:<workspace-id>:connector:<connector-id>",
  "audiences": [
    "api://AzureADTokenExchange"
  ],
  "description": "TillDev posture connector"
}

A sync makes 12 kinds of Azure Resource Manager read, each pinned to an API version, and follows the next page only on Resource Manager. It checks the subscription belongs to the connector’s tenant before reading anything else. A resource provider that isn’t registered leaves its type empty and is listed on the subscription rather than failing the sync. A sync makes at most 10,000 Azure calls and waits as long as Azure asks when it slows down. Only the global Azure cloud can be connected for now.

When sign-in is refused the sync fails and says why: no federated credential trusts the issuer or names this connector, the audience is wrong, the app or the tenant can’t be found, or the app is disabled.

Connect a Cloudflare account

Cloudflare has no identity federation for API access, so a Cloudflare connector reads with a read-only token you create. Create it as an Account API token on the account, or as a user token limited to it, at https://dash.cloudflare.com/profile/api-tokens, with only the permissions below. The token is sealed in TillSecrets as it arrives, shown only by its last four characters, and unsealed only for a sync that is running. The first sync starts as soon as the connector is added.

printf %s "$CF_TOKEN" | tilldev shield posture add cloudflare --account <account-id> --token-stdin --wait
tilldev shield posture trust <connector-id>                   # the permissions, for a replacement token
printf %s "$NEW_TOKEN" | tilldev shield posture token <connector-id> --token-stdin

Every call goes to the Cloudflare API with the token and nothing else. A sync first reads the account and stops if the token answers for a different one. Leave out a permission for what you don’t use and that type reads as partial, naming the permission it needs; a zone whose settings or DNS can’t be read keeps its name and lists what wasn’t read. A token Cloudflare no longer accepts fails the sync and says to replace it. Give the token read permissions only: TillDev never writes, and a token that can’t write can’t be misused if it ever leaks.

Connect a DigitalOcean team

DigitalOcean has no identity federation for its API either, so a DigitalOcean connector reads with a personal access token with custom scopes. Make it in the team you connect, at https://cloud.digitalocean.com/account/api/tokens, with only the read scopes below, and add the connector with the team’s UUID. The token is sealed in TillSecrets as it arrives, like a Cloudflare token, and the first sync starts at once.

printf %s "$DO_TOKEN" | tilldev shield posture add digitalocean --account <team-uuid> --token-stdin --wait
tilldev shield posture trust <connector-id>                   # the scopes, for a replacement token

A sync first reads the account and stops if the token belongs to another team. A scope left out makes its type partial and names the scope; without firewall:read Droplets are still read, but which firewalls guard them is left blank rather than guessed. Spaces buckets aren’t read: the DigitalOcean API can’t list them with a token.

What a sync changes

• A resource seen for the first time is added.
• A resource whose name, region or settings differ from the last read is marked changed.
• A resource is removed only when the sync read its whole type and didn’t find it. A type that couldn’t be read in full, because the provider refused or a cap was reached, keeps what it had, and the sync ends as partial with the reason.
• A removed resource that appears again comes back, with its history.

A sync that fails changes nothing and says why in words, such as a role that can no longer be assumed. Removed resources stay visible under Removed for 30 days; sync history is kept for 90 days. Disconnecting a connector drops its inventory, and its audit trail stays.

Checks and findings

After each sync, every resource is judged against the checks for its type. A check that fails opens a finding that names the fields that failed, such as internet_admin_ports = 22. A finding stays open while the check fails and resolves on its own when a later full read shows it fixed, when the resource leaves the inventory, or when the check is turned off. A check that needs a field the sync couldn’t read, because the provider didn’t answer or a permission was left out, is counted as not run: it never passes and never closes a finding. Open a resource in the inventory to see how every check judges it.

tilldev shield posture findings                              # failing checks, worst first
tilldev shield posture finding <finding-id>                  # the evidence, the fix, and any exception
tilldev shield posture checks --category network             # the library: level, mode and open count
tilldev shield posture check posture-aws-s3-logging off      # or alert, report, default
tilldev shield posture except <check-id> --resource <resource-id> --reason "…" --days 90
tilldev shield posture exceptions                            # --ended adds revoked and expired ones
tilldev shield posture drift                                 # what changed since each baseline
tilldev shield posture baseline <resource-id>                # or --connector <id>

The library, by category:

Modes and exceptions

Each check has a mode for the workspace:

• Alert opens findings, and a sync that finds new failures sends one message naming them over the workspace’s security notifications: email, Slack or a signed webhook. Critical and high checks alert by default.
• Report opens findings without alerting. Medium, low and informational checks report by default.
• Off doesn’t evaluate the check, and its open findings resolve on the next sync.

An exception accepts a risk you have decided to keep: for one resource, or for every resource a check applies to. It needs a reason of up to 500 characters and ends after 1 to 365 days. While it is in force the check still runs, but its findings move from Open to Excepted and send no alert. Revoking it, or letting it end, puts them back. Changing a mode, adding an exception and revoking one each take an owner or admin and are in the audit log.

Drift from a baseline

A resource’s first read is its baseline. When a later read differs in a setting that matters, the resource is marked drifted and listed under Drift with each changed field’s baseline and current value. Fields that change in normal use, such as sign-in times, status and versions, are left out, and a field the last read couldn’t see is never counted as a change. Accept the new settings as the baseline for one resource or for every drifted resource of a connector; whoever accepts it is recorded. The alert for new failures also says how many resources drifted in that sync.

Limits

Connecting, changing and disconnecting take an owner or admin, and every change and every sync started by hand is in the audit log. The API is under /api/v1/shield/posture in the API reference.