# Advanced Detection

The `advanced_detection` profile is an add-on that layers ML-powered, type-specific detection on top of any other profile. It does not replace a deployment profile — it extends one. Apply it alongside `code_agent`, `data_pipeline`, `multi_agent`, or any other profile when the baseline pattern-matching detection is not sufficient for your security requirements.

***

## When to use advanced detection

The [default policies](/agent-authorization-and-control-shield/policy-templates.md#default-policies) detect secrets and PII using pattern matching — regular expressions and known formats. This covers common cases (generic API key patterns, SSN format, credit card Luhn checks) but has two limitations:

1. **Pattern coverage gaps.** New secret formats, proprietary credential structures, or atypical PII representations may not be caught by patterns.
2. **Bulk detection.** The defaults do not distinguish between a single incidental PII match and a response that contains dozens of personal records (a data dump).

The `advanced_detection` profile addresses both:

* **Type-specific secret blocking** uses format-aware detection for high-value credential types rather than generic patterns
* **ML classifier-based PII** operates at a confidence threshold rather than a pattern match, catching atypical representations
* **Bulk PII detection** flags responses with 3 or more PII matches as a potential data dump

Use `advanced_detection` for:

* Financial services, healthcare, or other regulated industries
* Any deployment handling sensitive personal data at scale
* High-security environments where credential leakage has severe consequences
* Data pipelines where the content corpus is large and varied enough that pattern-based detection has meaningful gaps

***

## Profile files

***

### secrets.cedar — Type-specific credential blocking

Blocks secrets by specific format rather than relying on generic patterns. Each rule targets a distinct credential type.

**High-risk secret types:**

| Credential type                     | Detection basis                                              |
| ----------------------------------- | ------------------------------------------------------------ |
| AWS IAM access keys                 | `AKIA...` key ID format + secret key structure               |
| GCP service account JSON            | Service account JSON structure with private key              |
| Azure client secrets / certificates | Azure credential format detection                            |
| GitHub personal access tokens       | `ghp_`, `gho_`, `ghu_`, `ghs_` prefix formats                |
| SSH private keys                    | PEM header patterns (`BEGIN RSA PRIVATE KEY`, etc.)          |
| Database connection strings         | Connection URI formats for PostgreSQL, MySQL, MongoDB, Redis |

```cedar
@id("detection-block-high-risk-secret-types")
@severity("critical")
forbid(principal, action, resource)
when {
    context has secret_types &&
    (context.secret_types.contains("aws_key") ||
     context.secret_types.contains("gcp_service_account") ||
     context.secret_types.contains("azure_secret") ||
     context.secret_types.contains("github_token") ||
     context.secret_types.contains("ssh_private_key") ||
     context.secret_types.contains("database_url"))
};
```

**Token types:**

Bearer tokens, JWTs, and OAuth tokens/secrets are blocked when their specific format is detected. This is distinct from the default secrets policy, which uses broader `contains_secrets` signal — the type-specific rules fire even when the generic signal does not.

```cedar
@id("detection-block-api-keys")
@severity("high")
forbid(principal, action, resource)
when {
    context has secret_types &&
    (context.secret_types.contains("bearer_token") ||
     context.secret_types.contains("jwt") ||
     context.secret_types.contains("oauth_token") ||
     context.secret_types.contains("oauth_secret"))
};
```

***

### pii.cedar — ML classifier-based PII detection

Extends the default pattern-based PII detection with ML classifier output.

**Bulk PII detection:**

When 3 or more distinct PII instances are detected in a single response, it is treated as a data dump regardless of the PII types involved. This catches cases where individual matches might be below the blocking threshold but the aggregate volume indicates something is wrong.

```cedar
@id("detection-block-bulk-pii")
@severity("critical")
forbid(principal, action, resource)
when { context has pii_count && context.pii_count >= 3 };
```

**ML confidence threshold:**

Blocks when the ML PII classifier confidence is above 80, independent of the pattern-match result. This catches atypical PII representations that the regex patterns miss.

```cedar
@id("detection-block-pii-high-confidence")
@severity("high")
forbid(principal, action, resource)
when { context has pii_confidence && context.pii_confidence >= 80 };
```

**File operation PII block:**

Blocks file reads and writes where PII is detected in the content. This is an addition to the default policy, which only evaluates prompt content.

```cedar
@id("detection-block-pii-file-ops")
@severity("high")
forbid(
    principal,
    action in [Guardrails::Action::"read_file", Guardrails::Action::"write_file"],
    resource
)
when { context has pii_detected && context.pii_detected == true };
```

***

### threat\_severity.cedar — Severity catch-all

Blocks any content flagged as Critical severity by any detector, regardless of the specific detection category. This ensures that future detectors — including custom detectors added via webhooks — automatically contribute to blocking at the critical tier without requiring a new policy rule.

```cedar
@id("detection-block-critical-severity")
@severity("critical")
forbid(principal, action, resource)
when { context has highest_severity && context.highest_severity == "critical" };
```

***

## Applying the profile

`advanced_detection` is always applied alongside a deployment profile, not on its own.

{% tabs %}
{% tab title="Python" %}

```python
from highflame.shield import GuardrailsClient

client = GuardrailsClient(api_key="...")

# Always pair with a deployment profile
client.policies.load_profile("code_agent/*")
client.policies.load_profile("advanced_detection/*")
```

{% endtab %}

{% tab title="TypeScript" %}

```typescript
import { GuardrailsClient } from "@highflame/sdk";

const client = new GuardrailsClient({ apiKey: "..." });

await client.policies.loadProfile("data_pipeline/*");
await client.policies.loadProfile("advanced_detection/*");
```

{% endtab %}
{% endtabs %}

Common pairings:

| Deployment profile | Reason for pairing                                                  |
| ------------------ | ------------------------------------------------------------------- |
| `data_pipeline`    | Large/varied data corpus with higher gap risk in pattern detection  |
| `code_agent`       | Enterprise environments with AWS/GCP/Azure credential exposure risk |
| `multi_agent`      | High-security orchestrated deployments                              |
| `chat_assistant`   | Regulated industries with strict PII output requirements            |

***

## Related

* [Policy Templates](/agent-authorization-and-control-shield/policy-templates.md) — all available profiles and selection guide
* [Data Pipeline Policies](/agent-authorization-and-control-shield/policy-templates/data-pipeline-policies.md) — zero-tolerance PII and secrets for pipeline agents
* [Code Agent Policies](/code-agents/setting-up-policies.md) — filesystem and supply chain protection for coding agents


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.highflame.ai/agent-authorization-and-control-shield/policy-templates/advanced-detection-policies.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.