# CloudSensors

Which AWS-native sources and Vulnesis passes are read, for one account or for every account. Fields, YAML, HCL and CLI samples, and how apply treats it.

Which AWS-native sources and Vulnesis passes are read, for one account or for every account. The sources listed are turned on; every other source is turned off for that scope. Once a source is on, everything it reports is ingested: granularity stops at the source. Turning one off stops reading it and keeps the findings already ingested, with their triage history. Each source's consent record is a named inline policy on the execution role, attached by redeploying the stack, so set deploy to attach it in the same apply. Turning a source on needs a connected AWS account. Not stored yet for one account: CloudNativeSource.accountId exists and is keyed, but no route writes an account id and the stack deploy reads the sources for the whole tenant, so only account "*" applies today. A document naming an account validates, and applying it needs that write path and a per-account read in the deploy.

| | |
|---|---|
| `apiVersion` | `vulnetix.com/v1` |
| `kind` | `CloudSensors` |
| Group | [Cloud](/platform-iac/kinds/catalogue.md#cloud) |
| Status | **Served.** The [config engine](/platform-iac/reference/engine.md) plans and applies it. |
| Objects per tenant | many, keyed by `metadata.name` |
| Token and role | An owner, or a service account with the developer role (its ApiKey), or an Authentik access token for either. A member is refused with HTTP 403. See [Credentials for automation](/platform-iac/reference/config-api.md#credentials-for-automation). |
| Applied after | [`AwsConnection`](/platform-iac/kinds/aws-connection.md), [`AwsAccount`](/platform-iac/kinds/aws-account.md) (deleted before them) |
| Terraform resource | [`vulnetix_cloud_sensors`](/platform-iac/terraform/resources.md#vulnetix_cloud_sensors), imported by name (see [Terraform and OpenTofu](#terraform-and-opentofu)) |
| CLI | [`vulnetix config apply`](/platform-iac/cli/apply.md), CLI v3.165.1 and later. |
| Pinned schema | [`v1.19.1/CloudSensors.schema.json`](https://github.com/Vulnesis/config-schemas/releases/download/v1.19.1/CloudSensors.schema.json) |
| Newest schema | [`latest/CloudSensors.schema.json`](https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json) |
| First released in | [`v1.3.0`](https://github.com/Vulnesis/config-schemas/releases/tag/v1.3.0) |
| Print the built-in copy | `vulnetix config schema CloudSensors` |

## Minimal

Only the fields the kind requires. From `examples/CloudSensors/minimal.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: estate
spec:
  sources: [inspector, security-hub]
```

**HCL** (resource `vulnetix_cloud_sensors`)

```hcl
# Only the arguments the kind requires. From config-schemas examples/CloudSensors/minimal.yaml.

resource "vulnetix_cloud_sensors" "estate" {
  name    = "estate"
  sources = ["inspector", "security-hub"]
}
```

Every field that has a schema default, set to that default: [`terraform/cloud_sensors.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/cloud_sensors.tf) and [`yaml/CloudSensors.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/CloudSensors.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: estate
spec:
  sources: [inspector, security-hub]
EOF
```

## Advanced

Every field the kind supports, with a `when` expression where it takes one. From `examples/CloudSensors/advanced.yaml`.

**YAML**

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: estate
  labels:
    scope: all-accounts
  annotations:
    note: Only account "*" applies today; a per-account document validates but is not stored yet.
spec:
  account: "*"
  sources:
    - inspector
    - security-hub
    - guardduty
    - config
    - macie
    - access-analyzer
    - waf
    - compute
    - compute-artifacts
    - network-logs
    - eks-workloads
  deploy: true
```

**HCL** (resource `vulnetix_cloud_sensors`)

```hcl
# Every argument the kind supports. From config-schemas examples/CloudSensors/advanced.yaml.

resource "vulnetix_cloud_sensors" "estate" {
  name    = "estate"
  account = "*"
  deploy  = true
  sources = ["inspector", "security-hub", "guardduty", "config", "macie", "access-analyzer", "waf", "compute", "compute-artifacts", "network-logs", "eks-workloads"]
  labels = {
    scope = "all-accounts"
  }
  annotations = {
    note = "Only account \"*\" applies today; a per-account document validates but is not stored yet."
  }
}
```

Every field that has a schema default, set to that default: [`terraform/cloud_sensors.tf`](https://github.com/Vulnesis/platform-iac-examples/blob/main/terraform/cloud_sensors.tf) and [`yaml/CloudSensors.yaml`](https://github.com/Vulnesis/platform-iac-examples/blob/main/yaml/CloudSensors.yaml) in [Vulnesis/platform-iac-examples](https://github.com/Vulnesis/platform-iac-examples).

**CLI** (applies it)

```bash
export VULNESIS_ORG_ID=...    # the organization UUID
export VULNESIS_API_KEY=...   # the ApiKey of a developer or owner service account
vulnetix config apply -f - --manager gitops:acme/platform --auto-approve <<'EOF'
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: estate
  labels:
    scope: all-accounts
  annotations:
    note: Only account "*" applies today; a per-account document validates but is not stored yet.
spec:
  account: "*"
  sources:
    - inspector
    - security-hub
    - guardduty
    - config
    - macie
    - access-analyzer
    - waf
    - compute
    - compute-artifacts
    - network-logs
    - eks-workloads
  deploy: true
EOF
```

## Fields

Paths use dots for nesting and `[]` for the items of a list. **Required** means required whenever the parent object is present. A default is what the server uses when the field is left out.

| Field | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|
| <span id="apiVersion"></span>`apiVersion` | string | yes |  | exactly `vulnetix.com/v1` | The document format version. Every kind in this release is vulnetix.com/v1. |
| <span id="kind"></span>`kind` | string | yes |  | exactly `CloudSensors` | Always CloudSensors. |
| <span id="metadata"></span>`metadata` | object | yes |  | no other keys |  |
| <span id="metadata-name"></span>`metadata.name` | string | yes |  | pattern `^[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?$` | The object's name, unique per kind within a tenant. It is the natural key: plan, apply, export and the Terraform provider all address an object by kind and name. |
| <span id="metadata-org"></span>`metadata.org` | string | no |  | format `uuid` | The tenant (organization UUID) the document belongs to. When set, plan and apply refuse to run against any other tenant. |
| <span id="metadata-labels"></span>`metadata.labels` | object | no |  | map of string to string (length 0 to 256); keys match `^[a-z0-9]([a-z0-9._/-]{0,61}[a-z0-9])?$` | Free key/value labels. Stored with the object, never interpreted by the server. |
| <span id="metadata-annotations"></span>`metadata.annotations` | object | no |  | map of string to string (length 0 to 4096) | Free key/value notes for people and tools, such as a ticket link. |
| <span id="spec"></span>`spec` | object | yes |  | no other keys |  |
| <span id="spec-account"></span>`spec.account` | string | no | `*` | exactly `*`, or pattern `^[0-9]{12}$` | An AWS account id, or * for every account, including those connected later. One document per value. |
| <span id="spec-sources"></span>`spec.sources` | array of string | yes |  | items unique; each item: `inspector`, `security-hub`, `guardduty`, `config`, `macie`, `access-analyzer`, `waf`, `compute`, `compute-artifacts`, `network-logs`, `eks-workloads` | inspector: Amazon Inspector. security-hub: AWS Security Hub. guardduty, config, macie and access-analyzer: those products, read through Security Hub (one grant, filtered by product). waf: the AWS WAF configuration in front of the account. compute: SSM package inventory, EMR, EKS node groups, running ECS images, CIS AWS Foundations and CloudFormation template checks. compute-artifacts: read inside ECR image layers and Lambda code. network-logs: match Resolver and flow logs against malicious indicators. eks-workloads: list EKS pods and the images each runs; each cluster also needs an access entry you create. compute-artifacts, network-logs and eks-workloads have an effect only with compute on. |
| <span id="spec-deploy"></span>`spec.deploy` | boolean | no | `false` |  | Redeploy the pipeline stack after a change, so the execution role carries exactly the policies the sources turned on need. |

## Applying this kind

- **Command.** `vulnetix config apply -f <file>`; the CLI line above says from which release. Plan first with [`vulnetix config plan`](/platform-iac/cli/plan.md): it shows each object as create, update, delete or no change, with a `planHash` that apply then holds to. Apply writes in one transaction.
- **Manager.** Each object records the manager that applied it (`terraform`, `console` or `gitops:<repo>`). `--prune` deletes only objects its own manager owns. See [The manager](/platform-iac/cli/plan.md#the-manager) and the [config engine](/platform-iac/reference/engine.md).
- **Order.** Applied after [`AwsConnection`](/platform-iac/kinds/aws-connection.md) and [`AwsAccount`](/platform-iac/kinds/aws-account.md), so a document that refers to one by `metadata.name` can be in the same apply. Deleted before them.
- **Status.** Applied, Unchanged or Deleted, with no other status fields. The phases the engine reports are explained under [status phases](/platform-iac/reference/engine.md#status-phases).

## How apply treats it

- `account: "*"` is the choice for every account. An account id is an override for that account, which then reads exactly its own sources.
- Only the sources in the schema are written, and only rows whose state changes.
- `deploy: true` queues the stacks of the accounts the document covers (`"*"`: every enabled account without an override).
- Deleting an override sends the account back to `"*"`. Deleting `"*"` turns every source off.
- A per-account document needs the platform update `20261226020000_cloud_native_source_per_account`. Until it runs, plan blocks the document with the update's name, and `"*"` works as before.

## Terraform and OpenTofu

The resource is `vulnetix_cloud_sensors` in the `vulnetix/resolve` provider. Its arguments are the `spec` in snake case, beside `name`, `labels` and `annotations` from `metadata`. The Minimal and Advanced HCL are above. The provider's own reference is [vulnetix_cloud_sensors](https://registry.terraform.io/providers/vulnetix/resolve/latest/docs/resources/cloud_sensors).

Import an object that already exists by its name:

```shell
# Import an existing CloudSensors by its name (metadata.name).
terraform import vulnetix_cloud_sensors.estate estate
```

Install, authentication and how state is read: [Terraform and OpenTofu](/platform-iac/terraform.md).

## More examples

`examples/CloudSensors/sensors.yaml` from `Vulnesis/config-schemas`:

```yaml
# yaml-language-server: $schema=https://github.com/Vulnesis/config-schemas/releases/latest/download/CloudSensors.schema.json
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: estate
spec:
  account: "*"
  sources: [inspector, security-hub, guardduty, waf, compute]
  deploy: true
---
apiVersion: vulnetix.com/v1
kind: CloudSensors
metadata:
  name: production
spec:
  account: "123456789012"
  sources: [inspector, security-hub, guardduty, waf, compute, compute-artifacts, network-logs, eks-workloads]
```

Check a file with `vulnetix config validate -f <file>`. See [Validate documents](/platform-iac/cli/validate.md). In an editor, start the file with the [schema comment](/platform-iac/schemas/editors.md).
