---
name: trust-center-api-management
description: Use for **ALL** Trust Center scanner management requests including: enabling/disabling scanners or packages, changing notification settings, modifying run schedules, or triggering scanner executions. **Always query current state before making changes.**
---

## Prerequisites

**MANDATORY: Load** [references/trust-center-api.md](../references/trust-center-api.md) — contains all Trust Center views, columns, stored procedure signatures, and the first-party scanner ID mapping.

## Instructions

When the user requests to manage Trust Center scanners or scanner packages, use the SQL API documented in the reference file.

**⚠️ IMPORTANT: Trust Center has a full SQL API for ALL scanner management operations.** This includes enabling/disabling scanners, enabling/disabling packages, changing schedules, configuring notifications, and triggering scanner runs. NEVER tell the user that scanner management must be done through the UI or that no API exists.

**⚠️ Always use `SCANNER_PACKAGE_ID` and `SCANNER_ID` column values from the views, never display names.** For example, use the `ID` column value from `snowflake.trust_center.scanner_packages`, not the `NAME` column.

---

### Scanner Package and Scanner Execution

Runs a scanner package or individual scanner. If a scanner package is executed, all scanners that are enabled in it will be executed. Packages or scanners that do not exist will fail if a user tries to execute them.

To execute an entire scanner package:
```sql
CALL snowflake.trust_center.execute_scanner('<SCANNER_PACKAGE_ID>');
```

To execute a specific scanner:
```sql
CALL snowflake.trust_center.execute_scanner('<SCANNER_PACKAGE_ID>', '<SCANNER_ID>');
```

---

### Scanner Package Enablement

Enables an entire scanner package and all scanners within it. Free scanner packages are enabled by default. Enabling a paid package will incur cost to the account.

```sql
CALL snowflake.trust_center.set_configuration('ENABLED', 'TRUE', '<PACKAGE_ID>');
```

---

### Scanner Package Disablement

Disables an entire scanner package. Disabling a paid package will stop future costs.


```sql
CALL snowflake.trust_center.set_configuration('ENABLED', 'FALSE', '<PACKAGE_ID>');
```

**Note**: The Security Essentials package is free and cannot be disabled. If the user requests this, inform them and check current Snowflake documentation for alternatives.

---

### Scanner Specific Enablement

Enables a specific scanner within a scanner package. Free scanners are typically enabled by default.

**⚠️ Prerequisite: The scanner's parent package must be enabled first.** A scanner cannot be enabled if its parent package is disabled. Always check the package state before enabling a scanner:

```sql
SELECT id, name, state
FROM snowflake.trust_center.scanner_packages
WHERE id = '<PACKAGE_ID>';
```

If the package `STATE` is not `TRUE`, enable the package first using Scanner Package Enablement (above), then enable the individual scanner:

```sql
CALL snowflake.trust_center.set_configuration('ENABLED', 'TRUE', '<PACKAGE_ID>', '<SCANNER_ID>');
```

---

### Scanner Specific Disablement

Disables a specific scanner within a scanner package. Disabling a paid scanner will stop future costs for that scanner.


```sql
CALL snowflake.trust_center.set_configuration('ENABLED', 'FALSE', '<PACKAGE_ID>', '<SCANNER_ID>');
```

**Note**: Any Security Essentials scanner cannot be disabled. If the user requests this, inform them and check current Snowflake documentation for alternatives.

---

### Scanner Package or Scanner-level Schedule Modification

Updates the package or scanner CRON schedule. If a package's schedule is updated, all scanners within it will be updated. Convert natural language date descriptions to CRON format.

For package-level schedule:
```sql
CALL snowflake.trust_center.set_configuration('SCHEDULE', 'USING CRON <SCHEDULE> UTC', '<PACKAGE_ID>', false);
```

For scanner-level schedule:
```sql
CALL snowflake.trust_center.set_configuration('SCHEDULE', 'USING CRON <SCHEDULE> UTC', '<PACKAGE_ID>', '<SCANNER_ID>');
```

**Note**: The Security Essentials package and contained scanners have a fixed schedule that cannot be modified. If the user requests this, inform them and check current Snowflake documentation for alternatives.

---

### Scanner Package or Scanner-level Notification Modification

Updates the package or scanner email notification configuration. If a package's notification is updated, all scanners within it will be updated.

#### Configuration Format

The notification configuration must follow this JSON format:
```json
{"NOTIFY_ADMINS":"TRUE","SEVERITY_THRESHOLD":"CRITICAL","USERS":[]}
```

- `SEVERITY_THRESHOLD`: One of `"CRITICAL"`, `"HIGH"`, `"MEDIUM"`, `"LOW"`
- `NOTIFY_ADMINS`: One of `"TRUE"`, `"FALSE"`
- `USERS`: Array of valid users from `snowflake.trust_center.users` view. **Only add users explicitly requested by the user.**

- When `NOTIFY_ADMINS` is true, users array even with value, will be ignored
- When `NOTIFY_ADMINS` is false and users is empty, this is considered invalid configuration
- An empty JSON string `{}` indicates no email notification for this package/scanner

#### Query Current Configuration

For a package:
```sql
SELECT notification 
FROM snowflake.trust_center.scanner_packages
WHERE id = '<SCANNER_PACKAGE_ID>';
```

For a scanner:
```sql
SELECT running_configuration_value
FROM snowflake.trust_center.configuration_view
WHERE configuration_name = 'NOTIFICATION'
  AND scanner_package_id = '<SCANNER_PACKAGE_ID>'
  AND scanner_id = '<SCANNER_ID>';
```

#### Apply Notification Changes

For package-level notification:
```sql
CALL snowflake.trust_center.set_configuration('NOTIFICATION', '<CONFIGURATION_JSON>', '<PACKAGE_ID>', false);
```

For scanner-level notification:
```sql
CALL snowflake.trust_center.set_configuration('NOTIFICATION', '<CONFIGURATION_JSON>', '<PACKAGE_ID>', '<SCANNER_ID>');
```

---

### Scanner Package or Scanner-level Notification Integration (Webhook) Configuration

`NOTIFICATION_INTEGRATION` is a separate configuration type from `NOTIFICATION` (email). It enables sending scanner findings to external systems (PagerDuty, AWS SNS, etc.) via outbound notification integrations. A package or scanner can have both email notifications and webhook notification integrations configured independently.

#### Prerequisites — Creating and Granting the Integration

For creating the notification integration itself (webhook, email, AWS SNS, etc.), load and follow [integrations/create-notification-integration/SKILL.md](../../../integrations/create-notification-integration/SKILL.md).

After creating the integration, the following grants are required so that the Snowflake Trust Center application can access the integration and any associated secrets on behalf of the account.

**✋ STOPPING POINT — Do NOT execute these grant commands without the user's explicit approval.** Present the grants to the user and explain:
- `GRANT USAGE ON INTEGRATION` allows the Trust Center application to send webhook payloads through the named notification integration.
- `GRANT READ ON SECRET` (only needed if the integration uses a secret, e.g., a PagerDuty routing key) allows the application to read the secret value at runtime to authenticate with the external endpoint.
- `GRANT USAGE ON DATABASE/SCHEMA` gives the application access to the database and schema where the secret is stored.

Wait for the user to confirm before running any of these statements.

```sql
-- Required: grant USAGE on the integration to the Snowflake application
GRANT USAGE ON INTEGRATION <integration_name> TO APPLICATION snowflake;

-- If the integration uses a secret (e.g., PagerDuty webhook key):
GRANT READ ON SECRET <db>.<schema>.<secret_name> TO APPLICATION snowflake;
GRANT USAGE ON DATABASE <db> TO APPLICATION snowflake;
GRANT USAGE ON SCHEMA <db>.<schema> TO APPLICATION snowflake;
```

#### Configuration Format

The configuration value is an array of JSON objects cast to string. Each object contains:

- `INTEGRATION_NAME` (required) — name of the notification integration created above
- `SEVERITY_THRESHOLD` (required) — minimum severity to trigger the webhook: `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`
- `INCLUDE_AT_RISK_ENTITIES_AND_FINDING_METADATA` (optional) — `'TRUE'` or `'FALSE'` (default `'FALSE'`)

> **⚠️ WARNING — `INCLUDE_AT_RISK_ENTITIES_AND_FINDING_METADATA`**
>
> When set to `'TRUE'`, at-risk entity details and finding metadata are included in the webhook payload. This data may contain **sensitive information** such as user names, IP addresses, role assignments, and other account-specific details. Because this data **leaves the Snowflake boundary** and is sent to the configured webhook destination, only enable this if you are comfortable with such metadata being transmitted to your external endpoint. Ensure your webhook destination meets your organization's data handling and security requirements.

**✋ STOPPING POINT — You MUST ask the user** whether they want to include at-risk entity details and finding metadata in the webhook payload before generating the configuration. Explain that enabling `INCLUDE_AT_RISK_ENTITIES_AND_FINDING_METADATA` sends sensitive data (user names, IPs, role assignments) outside Snowflake to their webhook endpoint, and ask them to confirm. **Do NOT silently default to `'FALSE'`** — always surface this choice explicitly.

#### Query Current Configuration

```sql
SELECT running_configuration_value
FROM snowflake.trust_center.configuration_view
WHERE configuration_name = 'NOTIFICATION_INTEGRATION'
  AND scanner_package_id = '<PACKAGE_ID>';
```

To check a specific scanner's configuration, add the scanner filter:

```sql
SELECT running_configuration_value
FROM snowflake.trust_center.configuration_view
WHERE configuration_name = 'NOTIFICATION_INTEGRATION'
  AND scanner_package_id = '<PACKAGE_ID>'
  AND scanner_id = '<SCANNER_ID>';
```

#### Apply Notification Integration Changes

For package-level configuration:
```sql
CALL snowflake.trust_center.set_configuration(
  'NOTIFICATION_INTEGRATION',
  ARRAY_CONSTRUCT(
    OBJECT_CONSTRUCT(
      'SEVERITY_THRESHOLD', 'HIGH',
      'INTEGRATION_NAME', 'MY_PAGERDUTY_INT'
    )
  )::VARCHAR,
  '<PACKAGE_ID>'
);
```

For scanner-level configuration:
```sql
CALL snowflake.trust_center.set_configuration(
  'NOTIFICATION_INTEGRATION',
  ARRAY_CONSTRUCT(
    OBJECT_CONSTRUCT(
      'SEVERITY_THRESHOLD', 'CRITICAL',
      'INTEGRATION_NAME', 'MY_PAGERDUTY_INT',
      'INCLUDE_AT_RISK_ENTITIES_AND_FINDING_METADATA', 'TRUE'
    )
  )::VARCHAR,
  '<PACKAGE_ID>',
  '<SCANNER_ID>'
);
```

#### Troubleshooting Webhook Delivery

Use the `notification_history` view and `NOTIFICATION_HISTORY()` function to debug delivery issues:

```sql
SELECT * FROM snowflake.trust_center.notification_history ORDER BY sent_on DESC;
SELECT * FROM TABLE(snowflake.information_schema.notification_history());
```

---

## Error Handling

**If a command fails:**

| Error | Resolution |
|-------|------------|
| `Insufficient privileges` | User needs ACCOUNTADMIN or TRUST_CENTER_ADMIN role. Ask user to verify their role. |
| `Object does not exist` | Verify package/scanner ID exists using the views before retrying. |
| `Invalid CRON expression` | Check CRON syntax: 5 fields (minute, hour, day-of-month, month, day-of-week). |
| `Invalid notification format` | Verify JSON structure and that all users exist in `snowflake.trust_center.users`. |
| `Integration not found` or `does not exist` (notification integration) | Verify the integration name matches an existing notification integration. Confirm it was created with `CREATE NOTIFICATION INTEGRATION`. |
| `Insufficient privileges on integration` | Ensure `GRANT USAGE ON INTEGRATION <name> TO APPLICATION snowflake;` has been run. If the integration uses a secret, also grant `READ` on the secret and `USAGE` on its database/schema. |
| `Invalid notification integration configuration` | Verify the value is an `ARRAY_CONSTRUCT(...)::VARCHAR` containing objects with required keys `INTEGRATION_NAME` and `SEVERITY_THRESHOLD`. Check that `SEVERITY_THRESHOLD` is one of `LOW`, `MEDIUM`, `HIGH`, `CRITICAL`. |
| Webhook delivery failures (visible in `notification_history`) | Check `snowflake.trust_center.notification_history` and `TABLE(snowflake.information_schema.notification_history())` for error details. Common causes: endpoint unreachable, authentication failure, or secret expired. |
| Unknown error | Present full error message to user and ask for guidance. |
