# AI Context Refinement
Source: https://docs.zenable.io/ai-context-refinement
Automated maintenance of coding agent context files
## Overview
Zenable automatically analyzes your repositories to maintain high-quality AI context files aligned with your organization's requirements.
## How It Works
Scans your repository for AI context files, compares content against your configured requirements, and opens a PR with suggested improvements if issues are found.
**Files analyzed include:**
* **Claude Code**: `**/CLAUDE.md`, `**/.claude/rules/**/*.md`
* **Cursor**: `.cursorrules`, `.cursor/rules/**/*.mdc` (repository root only)
* **OpenAI Codex**: `**/AGENTS.md`
* **GitHub Copilot**: `.github/copilot-instructions.md`, `.github/instructions/**/*.md`
* **Devin Desktop**: `**/AGENTS.md`, `**/.devin/rules/**/*.md`
* **Antigravity CLI**: `**/GEMINI.md`
* **Kiro**: `**/.kiro/steering/**/*.md`
### Imported files (`@`-imports)
Context files often pull in another file with an `@path` reference—for example, a `CLAUDE.md` containing `@AGENTS.md`. Zenable resolves these imports and suggests a shared improvement in the file that actually owns the content (the imported file), instead of duplicating it in every file that references it. When the referenced file is itself a recognized context file, it's refined in its own right.
A **root context file** is a recognized context file that is not imported by
another recognized context file. It starts an independent analysis with its
standalone imports included. Each run analyzes at most 12 root context files.
## Enabling Analysis
Go to **Integrations > GitHub > Repos** in [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=ai-context-refinement\&utm_content=console)
Click on one or more repositories you want to analyze
Click the **Analysis** button to open the configuration modal
Toggle on **Refine Context** to enable AI context file improvements
Click **Add to Priority Queue** to run in the next nightly window
## When Analysis Runs
Once enabled, analysis runs automatically on a regular schedule.
### Priority Queue
Click **Add to Priority Queue** to request to prioritize your repository for a review.
## Viewing Results
When improvements are found, a PR is created in your repository. Review, modify, or merge as needed.
## Troubleshooting
Verify analysis is enabled and the repository is connected via GitHub integration. Use **Add to Priority Queue** if you need it sooner.
Your context files are already well-aligned with your requirements—no improvements needed.
## Next Steps
* Set up [GitHub PR reviews](/integrations/vcs-reviewers/github) for automated code review
* Define [custom policies](/use-cases/policy-as-code) for your organization
# Policy-Based Auto-Approvals
Source: https://docs.zenable.io/approval-policies
Turn analyzer quality scores into automated approvals with policies you define
## Overview
**Policies you define** decide which analyzer proposals move forward without waiting for a person. Zenable's analyzers already score every proposal against a rubric; a policy turns that score into an automated decision — accept proposals at or above a threshold, optionally decline proposals below a floor, and leave everything in between for human triage on [Proposals](/proposals). Nothing is auto-approved unless a policy you created says so.
Policies never bypass [approval workflows](/approval-workflows). If an approval flow gates the change, an automated approval files the same request a human would — governance stays the intentional last stop. A policy only replaces the *triage click*, not the approval.
Configure policies under **Approvals → Approval Policies**.
## What can be policy-accepted
Each policy selects one or more proposal kinds:
| Proposal kind | Produced by | What accepting does |
| - | - | - |
| New requirement proposals | Repository analysis of merged PRs | Promotes the proposed requirement to an active (beta) requirement and queues guardrail generation |
| Requirement refinements | Requirement refinement | Promotes the proposed new version to the family's live version |
| Requirement merges | Requirement evolution analysis | Promotes the merged requirement, records lineage, and deprecates the source requirements |
| Requirement splits | Requirement evolution analysis | Promotes every split result, records lineage, and deprecates the source requirement |
Merges and splits apply atomically: nothing changes until the whole operation (and any approval gating it) completes.
## Policies
A policy is the unit of configuration — create as many as you need:
* **Accept threshold (0–10)** — proposals scoring at or above this are accepted automatically.
* **Decline floor (0–10, optional)** — proposals scoring below this are declined automatically and move out of the triage queue. Zenable defaults to 6 and allows customization on the Agent Policies page.
* **Target selector (optional)** — narrow the policy to matching proposals using a reusable [target selector](/approval-workflows#target-types), e.g. only proposals for certain scopes or from a specific analysis source.
* **Daily cap (optional)** — a per-policy limit on automated accepts per day, on top of the tenant-wide daily budget. Proposals over budget simply wait for the next day (or a person).
* **Enabled** — disabled policies keep their configuration but never act.
Zenable provisions each tenant with a **Zenable default** policy as a starting point. It's yours to tune or delete — but editing turns it into your own policy, so you'll be asked to give it a new name (the "Zenable default" name is reserved for the policy as Zenable shipped it).
### When policies overlap
If several enabled policies match the same proposal, the **strictest threshold wins** — the proposal must satisfy every matching policy's bar to be accepted. A decline only happens when every floor-bearing policy would decline it **and** no matching policy would individually accept it; conflicting policies land the proposal on a human instead.
### Policies are governed changes
Approval policies decide what moves forward without a person, so changing one is itself gateable: approval flows can target `approval_policy_create`, `approval_policy_update`, and `approval_policy_delete`. A tenant can require a human sign-off on any change to what a policy accepts.
## Scoring rubrics
Every proposal kind is scored against a rubric of up to six weighted dimensions. Zenable ships built-in rubrics per kind; each dimension's description is the verbatim instruction the scoring model follows.
* **Customize** a rubric under **Approvals → Policy evaluation → Scoring Rubrics** — the editor seeds from the built-in defaults so you tune rather than start blank.
* **Tenant default** — mark one rubric per kind as the default; analyzers use it whenever no configuration profile picks a different one.
* **Configuration profiles** can link specific rubrics, so different repos can be scored against different bars.
Scores are computed when the proposal is created and stored with it — editing a rubric affects future proposals, not the existing queue.
## How runs work
The policy evaluation engine runs on Zenable's analysis scheduler (roughly daily) and compares each open proposal's stored score against your policies. You can also trigger a run on demand with **Run now**. Automated accepts show a **Policy-accepted** badge on Proposals, and every accept records which policies set the binding bar.
A tenant-wide daily budget bounds total automated accepts per day, independent of per-policy caps, so a runaway analyzer can never flood your requirement set.
## Reviewing evaluation runs
**Agent Evaluations** (under **Approvals → Agent Evaluations**) lets you browse the last 30 days of policy evaluation runs and inspect every proposal each run considered. See how your agent policys are working with a sankey chart, and adjust your thresholds while seeing how it would affect your current proposals.
## Required Permissions
| Permission | Grants |
| - | - |
| `approvals:read` | View approval policies and Agent Evaluations |
| `approvals:manage` | Create, edit, and delete approval policies; trigger a run; apply threshold changes |
| `settings:read` | View scoring rubrics |
| `settings:manage` | Create, edit, and delete scoring rubrics |
See [Roles and Permissions](/permissions) for which roles include these permissions.
## API Reference
### Approval Policies
| Method | Endpoint | Description | Permission |
| - | - | - | - |
| GET | `/api/data/approval-policies` | List policies (pass `?include_disabled=true` to include disabled) | `approvals:read` |
| POST | `/api/data/approval-policies` | Create a policy | `approvals:manage` |
| PUT | `/api/data/approval-policies/{id}` | Update a policy | `approvals:manage` |
| DELETE | `/api/data/approval-policies/{id}` | Delete a policy | `approvals:manage` |
| POST | `/api/data/approval-policies/run` | Schedule a run now | `approvals:manage` |
### Scoring Rubrics
| Method | Endpoint | Description | Permission |
| - | - | - | - |
| GET | `/api/data/approval-policy-rubrics` | List rubrics (filter with `?assessment_kind=`) | `settings:read` |
| GET | `/api/data/approval-policy-rubrics/defaults` | Built-in default rubric per proposal kind | `settings:read` |
| POST | `/api/data/approval-policy-rubrics` | Create a rubric | `settings:manage` |
| PUT | `/api/data/approval-policy-rubrics/{id}` | Update a rubric (new version) | `settings:manage` |
| DELETE | `/api/data/approval-policy-rubrics/{id}` | Delete a rubric | `settings:manage` |
# Approval Workflows
Source: https://docs.zenable.io/approval-workflows
Configure multi-phase approval flows for requirements and guardrails
Approval workflows are available on **Professional** and **Enterprise** plans.
## Overview
Approval workflows let you gate requirements or guardrail changes. Configure multi-phase flows with flexible approval criteria based on specific users, roles, or permissions.
Without an active approval flow, requirements and guardrail regenerations are auto-approved immediately. With a flow configured, submissions enter a **pending** state and require explicit approval before proceeding.
## Key Concepts
| Concept | Description |
| - | - |
| **Approval Flow** | A reusable workflow definition with one or more sequential phases |
| **Phase** | A step in the flow with its own approval expression (who must approve) |
| **Approval Expression** | A logical tree (AND/OR/NOT) of criteria that must be satisfied |
| **Approval Request** | A specific instance of a submission awaiting review |
| **Feedback** | Votes (upvote/downvote) and comments on pending requests |
## Target Types
Approval flows can be configured for these submission types. Create / update / delete are split per entity so different policies can apply to each (e.g. a flow could require approval on delete but not on create):
| Target Type | Description |
| - | - |
| `new_requirement` | New requirement proposals |
| `requirement_version` | Updates to existing requirements |
| `requirement_delete` | Deletion of a requirement family (cascades to the requirement's guardrails) |
| `requirement_override_create` | Creating a tenant override for a marketplace requirement |
| `requirement_override_update` | Modifying an existing tenant override |
| `requirement_override_delete` | Removing a tenant override |
| `guardrail_regeneration` | Guardrail code regeneration requests |
| `guardrail_custom_create` | Authoring a new tenant-owned custom guardrail |
| `guardrail_custom_update` | Modifying an existing custom guardrail |
| `guardrail_delete` | Deleting a custom guardrail |
| `guardrail_family_settings_change` | Changing a guardrail's runtime failure settings |
| `scope_create` | Authoring a new scope definition, or approving a proposed scope |
| `scope_update` | Modifying an existing scope definition |
| `scope_delete` | Deleting a scope definition |
| `target_selector_create` | Authoring a new approval-flow target selector |
| `target_selector_update` | Modifying an existing target selector |
| `target_selector_delete` | Deleting a target selector |
| `requirement_merge` | Merging multiple requirements into one |
| `requirement_split` | Splitting one requirement into several |
| `approval_policy_create` | Authoring a new [approval policy](/approval-policies) |
| `approval_policy_update` | Modifying an existing approval policy |
| `approval_policy_delete` | Deleting an approval policy |
### Pending state and final disposition
Approval-gated actions never reach their final state until the request is approved.
* **Creates and updates** stage the proposed data in the affected table itself, marked `PROPOSED` (overrides) or `PROPOSED` lifecycle (requirements). Read paths filter these out so users only see live state.
* **Deletes** carry no pending state on the row — the open approval request itself is the pending marker. On approve the row is soft-deleted via `deleted_at`; on reject the row is untouched. Soft delete keeps the audit trail intact and makes restoration trivial.
* An override **update** writes a new `PROPOSED` row whose `supersedes_id` points at the existing `ACTIVE` row. On approve, the superseded row is soft-deleted and the proposed row flips to `ACTIVE`. On reject, the proposed row is soft-deleted and the active row stays live.
### Specific-user criteria
`SPECIFIC_USER` criterion values are stored as `user_uid` (the stable 5-word identifier). The UI surfaces and accepts `login_identifier` (email / UPN / SSO sub) so authors and approvers see human-readable handles; the form picker stores the corresponding `user_uid` under the covers. Even when an approver holds `requirements:approve` or `guardrails:approve`, they can only decide on a request if they satisfy the active phase's expression — being named in a `SPECIFIC_USER` rule, for example.
## Creating an Approval Flow
Navigate to [Approval Management](https://www.zenable.app/approval-management?utm_source=docs\&utm_medium=web) and select the **Workflows** tab.
### Flow Configuration
1. **Name and description** - Give the flow a meaningful name
2. **Target types** - Select which submission types trigger this flow
3. **Phases** - Define one or more sequential approval phases
4. **Default flow** - Optionally mark as the default for its target types
5. **Auto-regenerate invalid guardrails without approval** - An optional configuration, shown only when `guardrail_regeneration` is a target type. When enabled, automatic regeneration due to a failure at runtime skips this flow and proceeds without approval. User-initiated regenerations still require approval.
### Target selectors (entity filters)
Target types decide *which kinds* of change a flow gates; an optional **target selector** narrows it to *which entities* — for example only enforced requirements, only marketplace ones, or only changes with a given lifecycle status.
Lifecycle matching is on the **resulting** status — the status the requirement will hold *after* the change (the outcome you're putting behind approval), not the status it's in now. The builder labels this rule **Resulting Status**. Match the state each change produces:
* Accepting a proposal brings it live at `beta` (the entry maturity — `stable` is a separate, later promotion), so gate go-lives with a `beta` selector.
* Declining a proposal lands it at `declined`, so gate declines with `declined`.
* Restoring a declined requirement returns it to `proposed` for re-triage, so gate restores with `proposed`.
### Approval Expressions
Each phase defines an approval expression using a logical tree:
* **Specific User** - A named user must approve (matched by user UID)
* **Role** - Any user with the specified role can approve
* **Permission** - Any user with the specified permission can approve
Combine criteria with **AND** (all must be satisfied), **OR** (any one suffices), or **NOT** (exclusion) operators. Expressions can be nested for complex approval requirements.
**Example:** "Requires approval from any Admin OR both the Security Auditor AND a Contributor"
```
OR
├── Role: Admin
└── AND
├── Role: Security Auditor
└── Role: Contributor
```
### Multi-Phase Flows
Phases execute sequentially. Each phase must be fully approved before the next begins. If any phase is rejected, the entire request is rejected.
**Example:** A two-phase flow for new requirements:
1. **Technical Review** - Any contributor approves
2. **Compliance Sign-off** - Security auditor approves
## Reviewing Approval Requests
Navigate to the **Pending Reviews** tab in [Approval Management](https://www.zenable.app/approval-management?utm_source=docs\&utm_medium=web).
Each request shows:
* The submitted entity (requirement name, guardrail code snippet)
* Current phase and progress
* **Approve** / **Reject** buttons (visible only if you have the required permission)
### Decisions
* **Approve** - Records your approval for the current phase. If the phase's approval expression is now satisfied, the flow advances to the next phase (or completes).
* **Reject** - Immediately rejects the entire request regardless of phase. The submitter is notified.
### Feedback
You can provide feedback on any pending request without making an approval decision:
* **Vote** - Upvote or downvote (one vote per user per request, toggleable)
* **Comment** - Up to 280 characters. Edits are tracked; the last 12 versions are stored.
## What Happens After Approval
| Target Type | On Approval | On Rejection |
| - | - | - |
| New requirement | Transitions from PROPOSED to BETA; guardrail generation triggers | Transitions to DECLINED |
| Requirement version | Transitions from PROPOSED to BETA; guardrail update triggers | Transitions to DECLINED |
| Requirement delete | Requirement soft-deleted; cascades to its guardrails | Submitter notified; no delete |
| Requirement override create / update | New row activates (PROPOSED → ACTIVE); for updates, the superseded ACTIVE row is soft-deleted | PROPOSED row soft-deleted |
| Requirement override delete | Override row soft-deleted | Submitter notified; no delete |
| Guardrail regeneration | Regeneration proceeds with stored parameters | Submitter notified; no regeneration |
| Custom guardrail create | New row becomes is\_latest=true | PROPOSED row soft-deleted |
| Custom guardrail update | New row becomes is\_latest=true; prior version flips to is\_latest=false | PROPOSED row soft-deleted |
| Custom guardrail delete | Guardrail soft-deleted | Submitter notified; no delete |
| Scope create / update | New row activates (PROPOSED → ACTIVE); for updates, the superseded ACTIVE row is soft-deleted | PROPOSED row soft-deleted |
| Scope delete | Scope soft-deleted | Submitter notified; no delete |
| Target selector create / update | New row activates (PROPOSED → ACTIVE); for updates, the superseded ACTIVE row is soft-deleted | PROPOSED row soft-deleted |
| Target selector delete | Selector soft-deleted | Submitter notified; no delete |
## Notifications
Zenable groups notifications into two categories, both configurable under **Settings → Notifications** in your [profile](https://www.zenable.app/settings?utm_source=docs\&utm_medium=web).
### Governance Activity
Immediate notifications for approval events:
| Event | Delivery | Recipients |
| - | - | - |
| Approval requested | Immediate | Eligible approvers for phase 1 |
| Decision made | Immediate | Submitter |
| Phase completed | Immediate | Next phase's eligible approvers |
| Fully approved/rejected | Immediate | Submitter |
| Feedback received | Daily digest | Submitter |
### Report Mail
An opt-in periodic digest that combines persisted notifications with calculated activity (findings, feedback, and PR/MR reviews) for the reporting period. Choose **daily**, **weekly**, or **monthly** cadence in your profile.
## Required Permissions
Approvals are fully transparent: anyone with `approvals:read` can see every request, every decision, every comment, and who voted which way. There is no per-record permission gating beyond `approvals:read`.
| Permission | Description |
| - | - |
| `approvals:read` | View approval flows, pending requests, decisions, and the feedback thread |
| `approvals:feedback` | Submit non-binding feedback (vote + comment) on an approval request |
| `approvals:manage` | Create, edit, and archive approval flow definitions, [approval policies](/approval-policies), and target selectors |
| `requirements:approve` | Cast a binding approve/reject decision on requirement proposals |
| `guardrails:approve` | Cast a binding approve/reject decision on guardrail requests |
See [Roles and Permissions](/permissions) for which roles include these permissions.
### Who can decide what
Approving a change requires both the permission to make the change and being named by the flow's current phase.
| To approve changes to | You need |
| - | - |
| Requirements — new ones, edits, lifecycle moves, deletions, merges, splits, and marketplace overrides | `requirements:approve` |
| Guardrails — regeneration, and custom guardrails your team authors | `guardrails:approve` |
| Scopes — creating, editing, deleting, or handing over ownership | `scopes:write` |
| Groups — creating, editing, deleting, or changing who belongs to one | `groups:write` |
| Tenant configuration — guardrail runtime settings, and applying a configuration proposal | `settings:manage` |
| The approval system itself — approval policies and target selectors | `approvals:manage` |
## API Reference
### Approval Flows
| Method | Endpoint | Description | Permission |
| - | - | - | - |
| GET | `/api/data/approval-flows` | List flows (pass `?include_archived=true` to include archived) | `approvals:read` |
| POST | `/api/data/approval-flows` | Create a new flow | `approvals:manage` |
| PUT | `/api/data/approval-flows/{id}` | Update a flow | `approvals:manage` |
### Approval Requests
| Method | Endpoint | Description | Permission |
| - | - | - | - |
| GET | `/api/data/approval-requests` | List approval requests (filterable by status, target\_type, submitted\_by) | `approvals:read` |
| GET | `/api/data/approval-requests/{id}` | Get request detail with phase instances | `approvals:read` |
| POST | `/api/data/approval-requests/{id}/decide` | Submit approve/reject decision on a request | Depends on what is being changed — see [Who can decide what](#who-can-decide-what) |
Decision request body:
```json theme={null}
{
"decision": "approve",
"comment": "Looks good to me"
}
```
The `decision` field accepts `approve` or `reject`. The optional `comment` field (max 280 characters) is recorded with the decision.
### Approval Feedback
| Method | Endpoint | Description | Permission |
| - | - | - | - |
| GET | `/api/data/approval-requests/{id}/feedback` | List all feedback for a request | `approvals:read` |
| POST | `/api/data/approval-requests/{id}/feedback` | Submit or update your feedback | `approvals:feedback` |
Feedback request body:
```json theme={null}
{
"vote": "upvote",
"comment": "I agree with this change"
}
```
The `vote` field accepts `upvote` or `downvote` (mutually exclusive, toggleable). Both fields are optional; you can vote without commenting or comment without voting. Feedback is upserted per user per request — submitting again updates your existing feedback. Comment edits are versioned (last 12 versions retained).
## Audit Logging
All approval actions are recorded in the audit log:
* Flow created, updated, or archived
* Decision made (approve/reject)
* Request created or resolved
* Feedback submitted or edited
Access audit logs via the **Audit** section in the [management console](https://www.zenable.app/audit?utm_source=docs\&utm_medium=web).
**Need help?** Contact us at [hello@zenable.io](mailto:hello@zenable.io)
# Audit Portal
Source: https://docs.zenable.io/audit-portal
Be sure that every change was checked against your requirements — and see where coverage gaps remain
## Overview
A finding tells you where a requirement was *violated*. The **Audit Portal** tells you the other half: which requirements were actually **evaluated** against which change — including the runs that came back clean and produced nothing.
That distinction is the whole point. A repository with zero findings looks identical to a repository Zenable silently stopped running on. The Audit Portal is what separates the two, so "requirement R was checked against change C" becomes a fact you can show an auditor rather than something inferred from the absence of a finding.
Find it under **Reporting → Audit Portal**.
## Who it's for
Three audiences read this page:
* **Engineering** — where are we covered, and where are the holes?
* **Cybersecurity** — are our controls being enforced?
* **Auditors** — show me proof the controls ran.
Auditors reach it through the **Security Auditor** role, which grants read-only access to the audit surface. See [Permissions](/permissions).
## What's on the page
### The assurance matrix
The centerpiece. It answers one question:
> Can we provide assurance that **these requirements** were enforced in **these scenarios**?
Your requirements run down the side; the **enforcement surfaces** run across the top — GitHub PR, GitLab MR, IDE / Agent, and CLI / Pre-commit. Each cell reports one of:
| State | Meaning |
| - | - |
| **Enforced** | The requirement ran on every change where the portal can prove it applied. Clean runs count. |
| **Partial** | A globally scoped requirement ran on some changes on that surface. |
| **Not covered** | A globally scoped requirement ran on **none** of the VCS changes on that surface. |
| **No activity** | No applicable evaluation was attested in the period. |
**"No activity" is not a gap.** It is deliberately distinct from *Not covered*: absence does not prove that a scoped requirement should have applied, and IDE / Agent and CLI / Pre-commit telemetry is optional.
The portal uses webhook and local-check attestations, not findings, as its evidence. An evaluation that produces zero findings still counts. Click any state for the evaluation and finding totals behind it; click the requirement name to open its full details.
The matrix is rebuilt nightly. The whole page reports **complete days only** — figures always end yesterday or earlier, so a partially-elapsed today can never make the numbers disagree with themselves.
### Landed without a check
Default-branch changes that landed with **no** Zenable evidence. This is the actionable list: each row is a change that reached your main branch unchecked.
Every way a change can land is counted — merge commits, squash merges, rebase merges, fork PRs, and **commits pushed directly to the default branch** (shown with a *Direct push* badge). Landings are observed from your VCS provider directly, so the count does not depend on webhook delivery.
A direct push counts as checked only when a Zenable check ran on that **exact commit** (for example a CLI or pre-commit check before pushing) — a direct push is not rewritten on landing, so commit identity is the honest test.
### PR discipline
The share of default-branch landings that arrived through a pull/merge request. Direct pushes bypass review entirely, so this number is the process-integrity signal auditors ask about alongside coverage.
### Filtering
The **repository** and **date range** filters at the top apply to the whole page at once — the matrix, the gap list, the evidence log, and the export all narrow together, and the filters ride the URL so a filtered view can be shared.
### Evidence log
Every check that ran, including the clean ones. Each entry records the change (repository, commit, change ref), the surface it ran on, how many checks executed, and how many findings came out.
## Exporting evidence
**Export evidence pack** downloads the bundle an auditor asks for over your selected period: the assurance matrix, the gap list, and the raw attestations behind both.
In order to export, you must have the `audit:export` permission. For more details, see the [Role Permission Matrix](/permissions#role-permission-matrix).
If a future release ever introduces a kind of change the coverage figures do not count, the portal will say so **in-product, next to the number it qualifies** — the limitation always travels with the data. Nothing is omitted today.
# Deployment & Adoption
Source: https://docs.zenable.io/deployment-adoption
Roll out quality guardrails across your team: from single developer to entire organization
Zenable scales from single repo to entire organization. Requirements are composable: layer them by team, product, environment, or any combination.
**Data Privacy**: We never retain or train on your code. [Learn more](https://www.zenable.io/security?utm_source=docs\&utm_medium=deployment-adoption\&utm_content=security)
## Deployment Levels
### Individual Developer
Install for all projects on your system (default).
```bash theme={null}
zenable install
```
[Setup guide →](/integrations/mcp/getting-started)
### Per-Repository
Project-specific installation.
```bash theme={null}
zenable install --project
```
### Team-Wide
Add [PR reviews](/integrations/vcs-reviewers/github), [pre-commit hooks](/integrations/pre-commit/getting-started), and shared standards.
### Organization-Wide
Set up your requirements once in our [management console](https://www.zenable.app?utm_source=docs\&utm_medium=web\&utm_content=deployment-adoption), and enforce them everywhere:
* Architecture decisions
* Security standards
* Compliance requirements (HIPAA, PCI-DSS, SOC2)
* Coding standards
* Product or customer requirements
[Learn about custom policies →](/use-cases/policy-as-code)
## Requirement Scopes
Target requirements precisely where they matter. Common scopes include:
* **Global**: Organization-wide (can be inherited, blocked, or force-inherited)
* **Repository**: Apply to specific repos (`acme/frontend-app`, `acme/payment-service`)
* **Team**: Target by team ownership (platform, mobile, backend)
* **File types**: Language-specific standards (`.py` → Python style, `.tsx` → React patterns)
* **Path patterns**: Target directories (`src/api/*` → API standards, `tests/*` → testing rules)
And more! See all scoping options in the [management console](https://www.zenable.app?utm_source=docs\&utm_medium=web\&utm_content=deployment-adoption).
Mix and match scopes for precise control. For example: stricter security for payment repositories, or TypeScript standards only for frontend teams.
## Rollout Strategies
**Week 1:** Install in 1-3 IDEs, measure bugs caught
**Week 2-4:** Add PR reviews + pre-commit hooks
**Month 2+:** Add company-wide requirements
**Day 1:** Install [GitHub](/integrations/vcs-reviewers/github)/[GitLab](/integrations/vcs-reviewers/gitlab) PR reviews
**Week 1:** Developers run `zenable install`
**Ongoing:** Add custom requirements as needed
**Week 1:** PR reviews on all repos
**Month 1:** Upload company requirements
**Ongoing:** Track metrics, refine
## Pricing
Built-in checks, IDE + PR reviews
Custom guardrails, 10x limits
Unlimited, dedicated environment
## Get Started
30 second setup
See team deployment
Configure requirements
# How It Works
Source: https://docs.zenable.io/how-it-works
Real-time AI code review with automated security checks and bug prevention
Zenable catches bugs and security issues before they reach your codebase through three core pillars:
## Our Approach
Enforce conformance and custom requirements directly in the SDLC. Provide context only when it matters to keep AI workflows efficient and precise.
Automatically measure, learn, and refine prompts, context, and guardrails to reduce token waste and keep integrations healthy.
Instrument the SDLC with metrics, telemetry, and audit-ready evidence. Turn usage data into actionable reports that double as compliance artifacts and performance KPIs.
## Technical Architecture
### Dual-Layer Validation
**Fast Deterministic Checks**
* Runs on every file save in milliseconds
* Catches known patterns: security vulnerabilities, code smells, style violations
**AI Code Review**
* Context-aware analysis of your codebase and requirements
* Provides working fixes, not just warnings
* Catches subtle bugs and logic errors
* Enforces architecture decisions and custom requirements
Both layers run in parallel. [See examples](/use-cases/preventing-ai-mistakes)
### Where Zenable Runs
**IDE Protection**
Works with [Cursor](/integrations/mcp/ide/cursor), [Claude Code](/integrations/mcp/ide/claude-code), [VS Code](/integrations/mcp/ide/vscode), [Codex](/integrations/mcp/ide/codex), [Devin Desktop](/integrations/mcp/ide/devin-desktop), [GitHub Copilot CLI](/integrations/mcp/ide/copilot), [Antigravity](/integrations/mcp/ide/antigravity), [Antigravity CLI](/integrations/mcp/ide/antigravity-cli), [Goose](/integrations/mcp/ide/goose), [Pi](/integrations/mcp/ide/pi), and more. [See our setup guide](/integrations/mcp/getting-started)
**Pre-Commit Hooks**
Block bad code at commit time. [Get started](/integrations/pre-commit/getting-started)
**PR Reviews**
Automated line-by-line feedback with fix suggestions. We support both [GitHub](/integrations/vcs-reviewers/github) and [GitLab](/integrations/vcs-reviewers/gitlab).
### Custom Requirements
Upload your requirements once, enforce everywhere:
* Architecture decisions
* Coding standards
* Compliance requirements (HIPAA, PCI-DSS, SOC2)
* Internal library usage rules
[Configure policies](/use-cases/policy-as-code) | [Deployment strategies](/deployment-adoption)
## Key Benefits
* Catch bugs as code is written, not in review
* Speed up code review with automated first-pass
* Automatically meet company requirements
* Zero learning curve—works with existing AI assistants
* No CI/CD changes needed
## Get Started
30 seconds
GitHub/GitLab
See what we catch
# Welcome to Zenable
Source: https://docs.zenable.io/index
AI code review that catches and fixes bugs before commit
# AI Guardrails That Learn From You
AI coding assistants move fast. Too fast to catch every SQL injection, hardcoded secret, or architecture violation they introduce.
**Zenable learns your team's standards and enforces them in real-time**, catching bugs and security issues as AI generates code. Upload your requirements once, protect your codebase forever.
**We never retain or train on your code.** Your IP remains yours. [Learn more](https://www.zenable.io/security?utm_source=docs\&utm_medium=index\&utm_content=security)
## Get Started
```bash theme={null}
zenable install
```
Don't have the Zenable CLI? [Get it here](/integrations/mcp/getting-started).
Works with Cursor, Claude Code, VS Code, Antigravity, and 50+ other IDEs. [Learn more](/integrations/mcp/getting-started)
Setup [GitHub](/integrations/vcs-reviewers/github) or [GitLab](/integrations/vcs-reviewers/gitlab) code reviews
Go to [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=index\&utm_content=configure-requirements) to add requirements or pick guardrails. Any configuration is automatically enforced across all IDE and code review integrations company-wide.
## How We Keep AI Code Safe
Enforce conformance and custom requirements directly in the SDLC. Provide context only when it matters to keep AI workflows efficient and precise.
Automatically measure, learn, and refine prompts, context, and guardrails to reduce token waste and keep integrations healthy.
Instrument the SDLC with metrics, telemetry, and audit-ready evidence. Turn usage data into actionable reports that double as compliance artifacts and performance KPIs.
## How It Works
Zenable combines fast deterministic security checks with AI-powered code review to catch issues instantly:
* **Real-Time Analysis**: Checks code as your AI generates it
* **Auto-Fix**: Get working fixes for security vulnerabilities and quality issues
* **Custom Standards**: Enforce your team's architecture decisions and coding standards
* **Multi-Layer Protection**: IDE checks, pre-commit hooks, and PR reviews work together
[Learn more about how Zenable works →](/how-it-works)
## See It In Action
```python theme={null}
# ❌ AI generates:
def get_user(user_id):
query = f"SELECT * FROM users WHERE id = {user_id}" # SQL injection risk
return db.execute(query)
# ✅ Zenable fixes:
def get_user(user_id):
query = "SELECT * FROM users WHERE id = ?" # Parameterized query
return db.execute(query, (user_id,))
# Zenable caught SQL injection and auto-fixed
```
[See more examples →](/use-cases/preventing-ai-mistakes)
## Enterprise-Grade Features
Upload your requirements, architecture decisions, and coding standards. Zenable automatically enforces them across your entire team. [Learn about policy as code →](/use-cases/policy-as-code)
Automatically analyze and document existing codebases to identify security gaps, technical debt, and compliance issues. [Explore code assessment →](/use-cases/code-assessment)
Instrument your SDLC with metrics, telemetry, and audit-ready evidence. Turn usage data into actionable reports that feed continuous improvement while doubling as compliance artifacts and performance KPIs. [View compliance features →](/use-cases/security-assessment)
Analyze codebases for vulnerabilities, technical debt, and compliance gaps. Data-driven security insights across your entire application. [Explore security assessment →](/use-cases/security-assessment)
## Ready to Stop Shipping Bugs?
Get started in 30 seconds
See Zenable in action
Discuss enterprise features
# AWS SCP
Source: https://docs.zenable.io/integrations/guardrails/aws-scp
AWS Organization-level service control policies
## Overview
AWS Service Control Policies enforce guardrails at the AWS account or organizational unit level. They act as permission boundaries in the cloud control plane, preventing actions regardless of IAM permissions.
## Capabilities
* Organization-wide enforcement across all accounts
* Allow-list and deny-list strategies that define permission boundaries
* Condition-based controls (regions, services, encryption requirements)
* Applies to all principals in target accounts (except the management account and service-linked roles)
## Limitations
* Requires an AWS Organization with all features enabled
* Only applicable to AWS cloud environments -- check out [Azure Policy](/integrations/guardrails/azure-policy) for Azure or [Google Cloud Organization Policy](/integrations/guardrails/gcp-org-policy) for Google Cloud environments
* Cannot grant permissions, only restrict them
## Generated Format
* **Language:** JSON
* **Structure:** IAM policy documents with `Effect`, `Action`, `Resource`, and `Condition` fields
* **Execution:** Applied via AWS Organizations console or API
## Example Guardrail
```json theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyUnencryptedS3PutObject",
"Effect": "Deny",
"Action": "s3:PutObject",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"s3:x-amz-server-side-encryption": "aws:kms"
}
}
}
]
}
```
Learn more at [AWS SCP documentation](https://docs.aws.amazon.com/organizations/latest/userguide/orgs_manage_policies_scps.html).
# Azure Policy
Source: https://docs.zenable.io/integrations/guardrails/azure-policy
Azure resource compliance enforcement
## Overview
Azure Policy enforces compliance on Azure resources at the resource provider level. Policies evaluate resource properties during creation, updates, and on a regular compliance cycle, ensuring resources meet organizational standards.
## Capabilities
* Enforce compliance at the Azure subscription or management group level
* Multiple effects: `Deny`, `Audit`, `Modify`, `Append`, `DeployIfNotExists`, `AuditIfNotExists`, `DenyAction`, and `Disabled`
* Built-in and custom policy definitions
* Initiative (policy set) grouping for compliance standards
## Limitations
* Requires an Azure subscription
* Only applicable to Azure cloud environments -- check out [AWS SCP](/integrations/guardrails/aws-scp) for AWS or [Google Cloud Organization Policy](/integrations/guardrails/gcp-org-policy) for Google Cloud environments
## Generated Format
* **Language:** JSON
* **Structure:** Azure Policy definition with `policyRule` containing `if`/`then` conditions
* **Execution:** Applied via Azure Portal, CLI, ARM templates, Bicep, Terraform, or REST API
## Example Guardrail
```json theme={null}
{
"properties": {
"displayName": "Require minimum TLS 1.2 on storage accounts",
"policyType": "Custom",
"mode": "All",
"parameters": {},
"policyRule": {
"if": {
"allOf": [
{
"field": "type",
"equals": "Microsoft.Storage/storageAccounts"
},
{
"field": "Microsoft.Storage/storageAccounts/minimumTlsVersion",
"notEquals": "TLS1_2"
}
]
},
"then": {
"effect": "deny"
}
}
}
}
```
Learn more at [Azure Policy documentation](https://learn.microsoft.com/en-us/azure/governance/policy/overview) and [policy definition structure](https://learn.microsoft.com/en-us/azure/governance/policy/concepts/definition-structure-basics).
# Checkov
Source: https://docs.zenable.io/integrations/guardrails/checkov
Infrastructure-as-code static analysis
## Overview
Checkov scans IaC source files for misconfigurations before deployment. It supports Terraform, CloudFormation, Kubernetes YAML, Dockerfiles, and other IaC formats.
## Capabilities
* Static analysis of IaC files without requiring a build or deployment
* Supports Terraform, CloudFormation, ARM templates, K8s manifests, Dockerfiles, Helm charts
* Custom Python checks for organization-specific rules
* Graph-based analysis for cross-resource relationships within IaC
## Limitations
* Only applicable to IaC and config files -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for application source code
* Does not test runtime infrastructure state -- check out [Goss](/integrations/guardrails/goss) for runtime validation
## Generated Format
* **Language:** Python
* **Structure:** Custom Checkov check classes extending `BaseCheck`
* **Execution:** `checkov --external-checks-dir -d `
## Example Guardrail
```python theme={null}
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
from checkov.common.models.enums import CheckResult, CheckCategories
class S3EncryptionCheck(BaseResourceCheck):
def __init__(self):
name = "Ensure S3 bucket has server-side encryption"
id = "CKV_CUSTOM_1"
supported_resources = ["aws_s3_bucket"]
categories = [CheckCategories.ENCRYPTION]
super().__init__(name=name, id=id, categories=categories,
supported_resources=supported_resources)
def scan_resource_conf(self, conf):
if "server_side_encryption_configuration" in conf:
return CheckResult.PASSED
return CheckResult.FAILED
check = S3EncryptionCheck()
```
Learn more at [Checkov documentation](https://www.checkov.io/) and [custom Python policies](https://www.checkov.io/3.Custom%20Policies/Python%20Custom%20Policies.html).
# CodeQL
Source: https://docs.zenable.io/integrations/guardrails/codeql
Semantic code analysis with cross-file data flow tracking
## Overview
CodeQL builds a relational database from the entire codebase, then runs QL queries against it. This enables deep semantic analysis including cross-file data flow tracking, import analysis, and type hierarchy queries.
## Capabilities
* Cross-file data flow and taint tracking
* Control flow analysis across function boundaries
* Import and type hierarchy queries
* Security, correctness, and maintainability checks
* Supports C/C++, C#, Go, Java/Kotlin, JavaScript/TypeScript, Python, Ruby, Rust, Swift
## Limitations
* Requires a build process for compiled languages
* Not applicable to infrastructure or runtime concerns -- check out [Checkov](/integrations/guardrails/checkov) or [Goss](/integrations/guardrails/goss) for infrastructure validation
* Not suited for file organization/existence checks
## Generated Format
* **Language:** CodeQL (QL)
* **Structure:** Query files with metadata block (`@id`, `@name`, `@kind`, `@problem.severity` or `@security-severity`) and `from`-`where`-`select` clauses
* **Execution:** Requires CodeQL CLI and a database built from the codebase
## Example Guardrail
```codeql theme={null}
/**
* @name SQL injection from user input
* @description Untrusted data flows to SQL query
* @kind path-problem
* @id custom/sql-injection
* @security-severity 9.0
* @precision high
* @tags security
*/
import python
import semmle.python.dataflow.new.TaintTracking
module SqlInjectionConfig implements DataFlow::ConfigSig {
predicate isSource(DataFlow::Node source) {
source.asExpr().(Call).getTarget().getName() = "input"
}
predicate isSink(DataFlow::Node sink) {
sink.asExpr().(Call).getTarget().getName() = "execute"
}
}
module SqlInjectionFlow = TaintTracking::Global;
import SqlInjectionFlow::PathGraph
from SqlInjectionFlow::PathNode source, SqlInjectionFlow::PathNode sink
where SqlInjectionFlow::flowPath(source, sink)
select sink.getNode(), source, sink, "Untrusted input flows to SQL query"
```
Learn more at [CodeQL documentation](https://codeql.github.com/docs/), [writing queries](https://codeql.github.com/docs/writing-codeql-queries/about-codeql-queries/), and [query metadata](https://codeql.github.com/docs/writing-codeql-queries/metadata-for-codeql-queries/).
# Conftest
Source: https://docs.zenable.io/integrations/guardrails/conftest
OPA-based configuration file testing with cross-file support
## Overview
Conftest tests structured configuration data against Rego policies. It supports many config formats and can validate consistency across multiple files using the `--combine` flag.
## Capabilities
* Tests YAML, JSON, HCL, Dockerfile, TOML, XML, INI, and many more formats
* Cross-file analysis via `--combine` flag
* `deny`, `warn`, and `violation` rule types
* Structured error metadata via `violation` rules
## Limitations
* Tests structured config data, not application source code -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for source code analysis
* Does not test runtime infrastructure state -- check out [Goss](/integrations/guardrails/goss) for runtime validation
## Cross-File Analysis
By default, conftest processes each file independently. The `--combine` flag merges all input files into a single array where each element has:
* `path`: the file path
* `contents`: the parsed file data
This enables policies that correlate data across files -- e.g., verifying Deployment selectors match available Services, or ensuring config values are consistent across environments.
```bash theme={null}
# Each file tested independently
conftest test deployment.yaml service.yaml
# Files combined into single input array for cross-file checks
conftest test deployment.yaml service.yaml --combine
```
## Generated Format
* **Language:** Rego
* **Structure:** Policy files in `package main` with `deny`/`warn` rules
* **Execution:** `conftest test [--combine]`
## Example Guardrail
```rego theme={null}
package main
# Single-file check
deny contains msg if {
input.kind == "Deployment"
not input.spec.template.spec.securityContext.runAsNonRoot
msg := sprintf("Deployment %s must run as non-root", [input.metadata.name])
}
# Cross-file check (requires --combine)
deny contains msg if {
some i
input[i].contents.kind == "Deployment"
deploy := input[i].contents
not has_matching_service(deploy)
msg := sprintf("Deployment %s has no matching Service", [deploy.metadata.name])
}
has_matching_service(deploy) if {
some j
input[j].contents.kind == "Service"
input[j].contents.spec.selector.app == deploy.spec.selector.matchLabels.app
}
```
Learn more at [Conftest documentation](https://www.conftest.dev/) and [OPA Rego language](https://www.openpolicyagent.org/docs/latest/policy-language/).
# ESLint
Source: https://docs.zenable.io/integrations/guardrails/eslint
Pluggable linting for JavaScript and TypeScript
## Overview
ESLint is a pluggable static analyzer for JavaScript and TypeScript. Zenable generates an ESLint configuration that enables and configures the rules needed to enforce a requirement, drawing on core rules, plugin rules, and the `no-restricted-syntax` / `no-restricted-imports` selectors for bespoke patterns.
## Capabilities
* Static analysis of JavaScript and TypeScript without running the code
* Enforces code-quality, style, and security rules via core and plugin rules
* Bans specific syntax, APIs, or imports with actionable messages
* Configurable severity per rule (`off` / `warn` / `error`)
## Limitations
* JavaScript and TypeScript only -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for other languages
* Single-file analysis -- check out [CodeQL](/integrations/guardrails/codeql) for cross-file data-flow analysis
* Not applicable to infrastructure or config files -- check out [Checkov](/integrations/guardrails/checkov) or [Conftest](/integrations/guardrails/conftest)
* Does not test runtime state -- check out [Goss](/integrations/guardrails/goss)
## Generated Format
* **Language:** JSON
* **Structure:** An ESLint configuration object with a `rules` map (and `plugins` when plugin rules are used)
* **Execution:** `eslint --config .json --format json `
## Example Guardrail
```json theme={null}
{
"rules": {
"no-restricted-syntax": [
"error",
{
"selector": "CallExpression[callee.name='eval']",
"message": "eval() is forbidden; it enables code injection."
}
],
"eqeqeq": "error"
}
}
```
Learn more at the [ESLint documentation](https://eslint.org/docs/latest/) and the [rules reference](https://eslint.org/docs/latest/rules/).
# OPA Gatekeeper
Source: https://docs.zenable.io/integrations/guardrails/gatekeeper
Kubernetes admission control via Rego policies
## Overview
OPA Gatekeeper validates Kubernetes resources at admission using Rego policies. It extends Open Policy Agent for Kubernetes-native policy enforcement.
## Capabilities
* Validate and mutate K8s resources at admission time via Rego
* Constraint templates for reusable policy logic
* Audit mode for detecting existing violations
* Enforcement actions: `deny`, `dryrun`, and `warn`
## Limitations
* Requires a Kubernetes cluster with Gatekeeper installed
* Only applicable to Kubernetes workloads -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for application source code, or [Checkov](/integrations/guardrails/checkov) for IaC static analysis
## Generated Format
* **Language:** YAML with embedded Rego
* **Structure:** `ConstraintTemplate` with Rego in `spec.targets[].rego` and accompanying `Constraint` resource
* **Execution:** Applied to a K8s cluster via `kubectl apply`
## Example Guardrail
```yaml theme={null}
apiVersion: templates.gatekeeper.sh/v1
kind: ConstraintTemplate
metadata:
name: k8srequiredlabels
spec:
crd:
spec:
names:
kind: K8sRequiredLabels
validation:
openAPIV3Schema:
type: object
properties:
labels:
type: array
items:
type: string
targets:
- target: admission.k8s.gatekeeper.sh
rego: |
package k8srequiredlabels
violation[{"msg": msg}] {
provided := {label | input.review.object.metadata.labels[label]}
required := {label | label := input.parameters.labels[_]}
missing := required - provided
count(missing) > 0
msg := sprintf("Missing required labels: %v", [missing])
}
---
apiVersion: constraints.gatekeeper.sh/v1beta1
kind: K8sRequiredLabels
metadata:
name: require-team-label
spec:
match:
kinds:
- apiGroups: [""]
kinds: ["Namespace"]
parameters:
labels: ["team"]
```
Learn more at [OPA Gatekeeper documentation](https://open-policy-agent.github.io/gatekeeper/website/docs/) and [constraint templates](https://open-policy-agent.github.io/gatekeeper/website/docs/howto).
# Google Cloud Organization Policy
Source: https://docs.zenable.io/integrations/guardrails/gcp-org-policy
Google Cloud resource-configuration compliance enforcement
## Overview
Google Cloud's [Organization Policy Service](https://docs.cloud.google.com/organization-policy/overview) centralizes control over how resources can be configured across the Resource Manager hierarchy (organization → folder → project). It sets guardrails on **what** a resource may look like — restricting regions, services, and resource settings so teams can only create compliant resources.
Zenable generates a **custom organization policy constraint**: a [CEL](https://docs.cloud.google.com/organization-policy/create-custom-constraints) condition evaluated against a strongly-typed representation of a resource when it is created or updated, with an `ALLOW` or `DENY` action.
## When this is a good choice
| Requirement | Why Organization Policy fits |
| - | - |
| Prevent teams from creating or configuring noncompliant resources | Constraints evaluate create/update requests before the resource exists; a `DENY` blocks the noncompliant configuration outright. |
| Restrict regions, public IPs, allowed services, or resource settings | The condition reads the resource's own fields and allow/deny-lists values. |
| Write custom resource rules like Azure Policy definitions | Custom constraints are the Google Cloud equivalent — CEL over resource fields, checked on create/update. |
| Audit-only / test before enforcement | The enforcing policy supports dry-run: violations are audit-logged without denying. |
For AWS environments see [AWS SCP](/integrations/guardrails/aws-scp); for Azure see [Azure Policy](/integrations/guardrails/azure-policy).
## Capabilities
* Enforce at the organization, folder, or project level; descendants inherit by default
* CEL conditions over strongly-typed, service-specific `resource.*` fields
* `ALLOW` (permit only when the condition is true) or `DENY` (block when the condition is true)
* Enforced on `CREATE`, or `CREATE` and `UPDATE`
* Dry-run / audit mode to preview impact before enforcement
## Limitations
* Requires a Google Cloud organization (Resource Manager hierarchy)
* Only applicable to Google Cloud environments
* `UPDATE`-only constraints are not supported; most resource types allow up to 20 custom constraints
## Generated Format
* **Language:** YAML
* **Structure:** a single `CustomConstraint` document — `name` (`custom.`), `resourceTypes`, `methodTypes`, `condition` (CEL), `actionType`, and optional `displayName` / `description`
* **Execution:** created with `gcloud org-policies set-custom-constraint`, then enforced by an organization policy (`enforce: true`, or `dryRunSpec` for audit mode)
## Example Guardrail
```yaml theme={null}
name: custom.restrictComputeRegions
resourceTypes:
- compute.googleapis.com/Instance
methodTypes:
- CREATE
- UPDATE
condition: "resource.zone.startsWith('us-')"
actionType: ALLOW
displayName: Restrict Compute to US regions
description: Only allow Compute instances created or updated in US zones.
```
Once created, an organization policy enforces the constraint across the chosen scope:
```yaml theme={null}
name: projects/PROJECT_ID/policies/custom.restrictComputeRegions
spec:
rules:
- enforce: true
```
Learn more at the [Organization Policy overview](https://docs.cloud.google.com/organization-policy/overview) and [Create custom constraints](https://docs.cloud.google.com/organization-policy/create-custom-constraints).
# Goss
Source: https://docs.zenable.io/integrations/guardrails/goss
Server and container validation tests
## Overview
Goss validates server and container state by testing system properties like installed packages, running processes, open ports, and file contents. Tests run against built artifacts or live systems.
## Capabilities
* Test packages, files, ports, processes, services, users, groups, commands
* Fast execution (written in Go)
* YAML-based test definitions
* Container image testing via `dgoss`
## Limitations
* Requires a built container image or running server
* Not applicable to source code analysis -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for source code checks
* Tests runtime state, not code patterns
## Generated Format
* **Language:** YAML
* **Structure:** Goss test files with resource type sections (`package`, `file`, `port`, etc.)
* **Execution:** `goss validate` or `dgoss run `
## Example Guardrail
```yaml theme={null}
package:
openssl:
installed: true
versions:
semver-constraint: ">=3.0.0"
port:
tcp:443:
listening: true
file:
/etc/ssl/certs:
exists: true
filetype: directory
process:
nginx:
running: true
```
Learn more at [Goss documentation](https://goss.readthedocs.io/) and [gossfile reference](https://goss.readthedocs.io/en/stable/gossfile/).
# Kubernetes VAP
Source: https://docs.zenable.io/integrations/guardrails/kubernetes-vap
Native Kubernetes ValidatingAdmissionPolicies with CEL
## Overview
Kubernetes ValidatingAdmissionPolicies (VAP) provide native admission control using CEL (Common Expression Language) expressions. Alpha in Kubernetes 1.26, beta in 1.28, and GA since 1.30, they validate resources without external webhook dependencies.
## Capabilities
* Native K8s admission control (no external controllers needed)
* CEL expressions for policy logic
* Parameter resources for reusable, configurable policies
* Audit and enforce modes
## Limitations
* Requires Kubernetes 1.30+ for stable/GA support (alpha in 1.26, beta in 1.28)
* Only applicable to Kubernetes workloads -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for application source code, or [Checkov](/integrations/guardrails/checkov) for IaC static analysis
* CEL is less expressive than Rego for complex logic -- check out [OPA Gatekeeper](/integrations/guardrails/gatekeeper) if you need full Rego expressiveness
## Generated Format
* **Language:** YAML (with CEL expressions)
* **Structure:** `ValidatingAdmissionPolicy` and `ValidatingAdmissionPolicyBinding` resources
* **Execution:** Applied to a K8s cluster via `kubectl apply`
## Example Guardrail
```yaml theme={null}
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicy
metadata:
name: require-non-root
spec:
failurePolicy: Fail
matchConstraints:
resourceRules:
- apiGroups: [""]
apiVersions: ["v1"]
operations: ["CREATE", "UPDATE"]
resources: ["pods"]
validations:
- expression: "object.spec.containers.all(c, has(c.securityContext) && has(c.securityContext.runAsNonRoot) && c.securityContext.runAsNonRoot == true)"
message: "All containers must set securityContext.runAsNonRoot to true"
---
apiVersion: admissionregistration.k8s.io/v1
kind: ValidatingAdmissionPolicyBinding
metadata:
name: require-non-root-binding
spec:
policyName: require-non-root
validationActions:
- Deny
```
Learn more at [Kubernetes ValidatingAdmissionPolicy documentation](https://kubernetes.io/docs/reference/access-authn-authz/validating-admission-policy/) and [CEL language spec](https://github.com/google/cel-spec).
# Kyverno
Source: https://docs.zenable.io/integrations/guardrails/kyverno
Kubernetes admission controller policies
## Overview
Kyverno validates and mutates Kubernetes resource manifests at admission time. Policies are written in YAML, making them accessible without learning a separate policy language.
## Capabilities
* Validate, mutate, generate, and clean up K8s resources
* YAML-native policies
* Pattern-based matching with wildcards and anchors
* Image verification and signature checking
## Limitations
* Requires a Kubernetes cluster with Kyverno installed
* Only applicable to Kubernetes workloads -- check out [Semgrep](/integrations/guardrails/semgrep) or [CodeQL](/integrations/guardrails/codeql) for application source code, or [Checkov](/integrations/guardrails/checkov) for IaC static analysis
## Generated Format
* **Language:** YAML
* **Structure:** Kyverno `ClusterPolicy` or `Policy` resources with `validate`/`mutate` rules
* **Execution:** Applied to a K8s cluster via `kubectl apply`
## Example Guardrail
```yaml theme={null}
apiVersion: kyverno.io/v1
kind: ClusterPolicy
metadata:
name: require-run-as-nonroot
spec:
rules:
- name: run-as-non-root
match:
any:
- resources:
kinds:
- Pod
validate:
failureAction: Enforce
message: "Containers must run as non-root"
pattern:
spec:
containers:
- securityContext:
runAsNonRoot: true
```
Learn more at [Kyverno documentation](https://kyverno.io/docs/) and [writing policies](https://kyverno.io/docs/policy-types/overview/).
# Semgrep
Source: https://docs.zenable.io/integrations/guardrails/semgrep
Static analysis rules for pattern matching across many languages
## Overview
Semgrep (and OpenGrep) uses YAML rules to find code patterns via Abstract Syntax Tree matching. Rules detect vulnerabilities, anti-patterns, and policy violations in application code, IaC, and config files.
## Capabilities
* Pattern matching with metavariables (`$VAR`, `...`)
* Taint mode for tracking data flow from sources to sinks within a function (cross-function and cross-file tracking available with [Semgrep Pro](https://semgrep.dev/docs/semgrep-code/semgrep-pro-engine-intro))
* Supports 35+ languages
* Lightweight, fast execution with no build step required
## Limitations
* Analyzes **one file at a time** by default -- cross-file analysis available with [Semgrep Pro](https://semgrep.dev/docs/semgrep-code/semgrep-pro-engine-intro)
* Not applicable to runtime or infrastructure state checks -- check out [Goss](/integrations/guardrails/goss) for runtime validation, or [Checkov](/integrations/guardrails/checkov) for IaC static analysis
If you've got a paid Semgrep subscription and are looking for multi-file support, please let us know at [zenable.io/feedback](https://www.zenable.io/feedback?utm_source=docs\&utm_medium=guardrails-semgrep).
## Generated Format
* **Language:** YAML
* **Structure:** Semgrep rule files with `id`, `message`, `severity`, `languages`, and pattern specification fields
* **Execution:** `semgrep --config rule.yaml`
## Example Guardrail
```yaml theme={null}
rules:
- id: sql-injection-prevention
mode: taint
languages: [python]
severity: HIGH
message: User input flows to SQL query without sanitization
pattern-sources:
- pattern: request.args.get(...)
pattern-sinks:
- patterns:
- pattern: cursor.execute($QUERY, ...)
- focus-metavariable: $QUERY
pattern-sanitizers:
- pattern: sanitize(...)
```
Learn more at [Semgrep rule syntax](https://semgrep.dev/docs/writing-rules/rule-syntax), [pattern syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax), and [supported languages](https://semgrep.dev/docs/supported-languages).
## Custom guardrails
You can author your own semgrep / opengrep rules and have Zenable apply them alongside marketplace guardrails. Configure each custom guardrail directory under the engine it belongs to:
```yaml theme={null}
guardrails:
engines:
semgrep:
extras:
custom_guardrail_dirs:
- path: ~/.zenable/custom_guardrails/semgrep
recurse: true
opengrep:
extras:
custom_guardrail_dirs:
- path: ~/.zenable/custom_guardrails/opengrep
recurse: true
```
### `metadata.category`
Every custom rule must declare a `metadata.category` from the upstream semgrep set:
`best-practice`, `correctness`, `maintainability`, `performance`, `portability`, or `security`.
Zenable translates these to its own `FindingCategory` taxonomy at the boundary. Rules with `metadata.category: security` must also declare `confidence`, `likelihood`, `impact`, `subcategory`, `cwe`, `owasp`, `references`, `technology`, and `vulnerability_class` per the upstream [contributor requirements](https://semgrep.dev/docs/contributing/contributing-to-semgrep-rules-repository#fields-required-by-the-security-category).
You can use the `zenable guardrail validate` command in order to confirm your custom rule is valid for Zenable guardrail use, for instance:
```bash theme={null}
zenable guardrail validate opengrep ~/.zenable/custom_guardrails/semgrep/custom-no-eval.yaml
```
# MCP Server Installation
Source: https://docs.zenable.io/integrations/mcp/getting-started
Set up the Zenable MCP Server in your IDE using our automated installer
## Overview
The Zenable MCP (Model Context Protocol) Server enables your AI coding assistant to automatically check and improve your code against your
organization's requirements.
**Your code is safe**: We never retain or train on your code, regardless of tier. [Read our FAQ](https://zenable.io/faq?utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=faq)
## Quick Installation
The easiest way to install the Zenable MCP server is using our automated installer:
```bash theme={null}
# Install MCP server for all detected IDEs
zenable install
```
Don't have the Zenable CLI? Install it first:
```bash theme={null}
curl -fsSL https://cli.zenable.app/install.sh | bash
```
```powershell theme={null}
powershell -ExecutionPolicy Bypass -Command "irm https://cli.zenable.app/install.ps1 | iex"
```
Sometimes virus scanners [flag Go binaries as suspicious](https://go.dev/doc/faq#virus).
All Zenable binaries are signed with a platform-appropriate approach, and
every release ships with SHA-256 checksums that are always verified at
install time. On Windows, the binary is Authenticode signed (Azure Trusted
Signing) and that signature is always verified during installation. On
Linux and macOS, the binary is [cosign](https://www.sigstore.dev/) signed
and verified when cosign or Docker is available. If your scanner flags the
binary, please report it to your antivirus vendor.
**Want more features?** Check out [Professional](https://zenable.io/pricing?tier=pro\&utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=pricing-pro) or [Enterprise](https://zenable.io/pricing?tier=enterprise\&utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=pricing-enterprise) plans to unlock [advanced capabilities](https://zenable.io/pricing?tier=pro\&utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=pro-features) and increase your weekly limits.
This will automatically:
* Detect your installed IDEs
* Configure the MCP server for each IDE
* Install hooks where supported
* Provide IDE-specific post-installation instructions, as needed
## Supported IDEs
### Full Support ✅
The following IDEs are fully supported (via the MCP server, hooks, or both). Click each for detailed installation instructions:
* **[Amp](/integrations/mcp/ide/amp)**
* **[Cursor](/integrations/mcp/ide/cursor)**
* **[Claude Code](/integrations/mcp/ide/claude-code)**
* **[Codex](/integrations/mcp/ide/codex)**
* **[Devin Desktop](/integrations/mcp/ide/devin-desktop)**
* **[GitHub Copilot CLI](/integrations/mcp/ide/copilot)**
* **[Goose](/integrations/mcp/ide/goose)**
* **[Pi](/integrations/mcp/ide/pi)** (hooks only)
* **[Kiro](/integrations/mcp/ide/kiro)**
* **[VS Code](/integrations/mcp/ide/vscode)**
* **[Antigravity](/integrations/mcp/ide/antigravity)**
* **[Antigravity CLI](/integrations/mcp/ide/antigravity-cli)**
* **[Auggie](/integrations/mcp/ide/auggie)**
* **[OpenCode](/integrations/mcp/ide/opencode)**
### Enhanced Hook Support
**[Claude Code](/integrations/mcp/ide/claude-code)**, **[Cursor](/integrations/mcp/ide/cursor)**, **[Devin Desktop](/integrations/mcp/ide/devin-desktop)**, **[Kiro](/integrations/mcp/ide/kiro)**, **[Auggie](/integrations/mcp/ide/auggie)**, **[OpenCode](/integrations/mcp/ide/opencode)** (via its plugin system), **[Antigravity CLI](/integrations/mcp/ide/antigravity-cli)**, **[Goose](/integrations/mcp/ide/goose)** (via its Open-Plugin-Spec hooks), and **[Pi](/integrations/mcp/ide/pi)** (via its extension system, hooks only) have additional support for hooks, enabling advanced automation workflows like automatic code checking after file edits and intelligent context management.
**[Codex](/integrations/mcp/ide/codex)** has limited hook support (session start and stop only as of 2026-03-11).
## Installation Methods
For IDE-specific installation instructions, see the [individual IDE guides](/integrations/mcp/getting-started#supported-ides).
### Method 1: Automated Installation (Recommended)
```bash theme={null}
# Install globally for all projects (default)
zenable install
```
This makes Zenable available across all your projects.
**Want project-level installation?** Run `zenable install --project` from inside a git repository to install only for that project.
## Post-Installation
After installation:
1. **Restart your IDE** to load the new configuration
2. **Verify the connection** - The Zenable MCP server should appear in your IDE's MCP tools. You may need to manually run an authentication command to
initiate the login workflow.
3. **Test the integration** - Open the chat prompt and add a feature to a file, and see if recommendations appear
**Need perfect consistency?** While most IDEs are good at following the installed instructions, Claude Code, Cursor, Devin Desktop, Kiro, Auggie, OpenCode, and Antigravity CLI provide
deterministic hooks that ensure reliable code checking after every file edit. These hooks are automatically configured with the same `install` command from above.
## Advanced Options
### Install for Specific IDEs
```bash theme={null}
# Single IDE
zenable install cursor
# Install Zenable for all supported IDEs on your system
zenable install
```
## Troubleshooting
Common issues and solutions:
The installer looks for IDE configuration files and installed applications. If your IDE isn't detected:
1. Make sure the IDE is installed
2. Try specifying it explicitly: `zenable install `
3. Open an issue at [zenable.io/feedback](https://zenable.io/feedback?utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=feedback) or email [support@zenable.io](mailto:support@zenable.io)
1. Restart your IDE completely
2. Check the configuration file location is correct
3. Validate JSON syntax in the configuration file
4. Check IDE logs for errors
The MCP server reviews files that are **modified during the agent session** (between prompt submit and agent stop). Some scenarios result in files not being reviewed:
* **File created then deleted**: If the agent creates a temporary file and removes it before stopping, there's nothing to review
* **File reverted to original state**: If a file was modified before your prompt but the agent reverts it back to its original content, the file is no longer changed so there's nothing new to review
* **File unchanged during session**: If a file was already dirty when you submitted your prompt but the agent didn't touch it, it won't be reviewed
* **File created outside the workspace**: Files created or modified outside the IDE's configured workspace are not reviewed unless the IDE passes us those file paths
* **File stashed without pop**: If the agent stashes changes and doesn't pop them back, the files aren't in the working tree and won't be reviewed
These are expected behaviors — the MCP server focuses on what the agent actually changed during the current session.
**For complete coverage**: Use [GitHub](/integrations/vcs-reviewers/github) or [GitLab](/integrations/vcs-reviewers/gitlab) PR/MR review bots alongside MCP hooks. The server-side bots review all changes in your pull/merge request, catching anything the MCP hooks might miss.
If the agent performs a **rebase**, **merge**, or **git pull** during a session, the review may include files from upstream commits that the agent didn't write. This happens because the hook compares your code against a checkpoint taken at prompt submit time, and these operations bring in external commits that widen the diff.
This is by design — reviewing extra files is safer than missing the agent's actual changes. The extra files automatically drop off on the next review cycle as the checkpoint advances past the merge/rebase point.
Common triggers:
* `git rebase main` — base branch files appear in diff
* `git merge main` or `git pull` — upstream files appear in diff
* `git cherry-pick` — cherry-picked commit's files appear in diff
This is a one-time effect per operation. After the first review, subsequent reviews only include files the agent changed since the last review.
For more detailed troubleshooting, see our [troubleshooting guide](/integrations/mcp/troubleshooting).
## Next Steps
* Learn about the [MCP Server](/integrations/mcp/server) and the tools it exposes to your assistant
* [Assess existing codebases](/use-cases/code-assessment)
* [Configure policies](https://www.zenable.app?utm_source=docs\&utm_medium=mcp-getting-started\&utm_content=configure-policies) for your team
# Amp
Source: https://docs.zenable.io/integrations/mcp/ide/amp
Set up the Zenable integration in Amp to run AI coding guardrails and conformance checks directly inside Sourcegraph's Amp agent.
## Quick Install
```bash theme={null}
zenable install amp
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Amp.
***
The below is a minimal example. Consider using the quick install command to handle this automatically.
### Option 1: Using Amp CLI (Recommended)
```bash theme={null}
# Add the MCP server
amp mcp add zenable https://mcp.zenable.app/
# Approve the server (required for workspace-scoped servers)
amp mcp approve zenable
# Authenticate with Zenable
amp mcp oauth login zenable \
--server-url https://mcp.zenable.app/ \
--client-id BwZkedovVV2bIPmxmK3crzdHmTdRqjv4 \
--auth-url https://zenable.us.auth0.com/authorize \
--token-url https://zenable.us.auth0.com/oauth/token \
--scopes "openid,profile,email"
```
### Option 2: Manual Configuration File
Add the following to your settings file:
```json theme={null}
{
"amp.mcpServers": {
"zenable": {
"url": "https://mcp.zenable.app/"
}
},
"amp.mcpPermissions": [
{ "matches": { "url": "https://mcp.zenable.app/*" }, "action": "allow" }
],
"amp.permissions": [
{ "tool": "mcp__zenable_*", "action": "allow" }
]
}
```
```bash Global (all projects) theme={null}
~/.config/amp/settings.json
```
```bash Project-specific theme={null}
.amp/settings.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
For more details on MCP configuration in Amp, see the [Amp MCP documentation](https://ampcode.com/manual#mcp).
# Antigravity
Source: https://docs.zenable.io/integrations/mcp/ide/antigravity
Set up the Zenable integration in Google Antigravity to enforce AI coding guardrails and conformance checks as you build.
## Quick Install
```bash theme={null}
zenable install antigravity
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Antigravity.
***
* **Global installs**: Use the Antigravity CLI (`antigravity --add-mcp`) - works on all platforms
* **Project installs**: Use file-based configuration at `/.vscode/mcp.json`
### Global Installation (CLI)
For global installations, if you have the `antigravity` command available:
```bash theme={null}
antigravity --add-mcp '{"name":"zenable","url":"https://mcp.zenable.app/","type":"http"}'
```
This works on all platforms (macOS, Windows, Linux).
### Project Installation (File)
For project-level installations, place the following configuration:
```json theme={null}
{
"servers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
},
"inputs": []
}
```
In this file location within your repository:
```bash theme={null}
/.vscode/mcp.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
# Antigravity CLI
Source: https://docs.zenable.io/integrations/mcp/ide/antigravity-cli
Set up the Zenable integration in Antigravity CLI, Google's successor to Gemini CLI, for AI coding guardrails and conformance checks in the terminal.
Antigravity CLI is Google's successor to Gemini CLI. If you're migrating, see [Google's migration guide](https://antigravity.google/docs/gcli-migration).
## Quick Install
```bash theme={null}
zenable install antigravity-cli
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Antigravity CLI.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"mcpServers": {
"zenable": {
"serverUrl": "https://mcp.zenable.app/"
}
}
}
```
In this file location:
```bash theme={null}
~/.gemini/antigravity-cli/mcp_config.json
```
For a project-scoped install, use `.agents/mcp_config.json` in your workspace instead.
Only `serverUrl` is needed — Antigravity authenticates automatically via OAuth dynamic client registration. Trigger the login from Antigravity's MCP/Customizations settings (the "Authenticate" action) if prompted.We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
# Auggie
Source: https://docs.zenable.io/integrations/mcp/ide/auggie
Set up the Zenable integration in Auggie, Augment Code's CLI agent, to add AI coding guardrails and conformance checks.
## Quick Install
```bash theme={null}
zenable install auggie
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Auggie.
This installs both the MCP server and Auggie hooks for real-time code checking.
***
The below is a minimal example. Consider using the quick install command to handle this automatically.
Use the Auggie CLI to add the Zenable MCP server:
```bash theme={null}
auggie mcp add zenable --transport http --url https://mcp.zenable.app/
```
To verify the installation:
```bash theme={null}
auggie mcp list
```
To remove:
```bash theme={null}
auggie mcp remove zenable
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Hooks run automatically to check for conformance issues. The quick install command sets this up for you.
Place the following configuration in `~/.augment/settings.json` (global) or `.augment/settings.json` (project):
```json theme={null}
{
"hooks": {
"SessionStart": [
{
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
]
}
}
```
This uses [Auggie's hook system](https://docs.augmentcode.com/cli/hooks?utm_source=zenable_docs\&utm_medium=web) to run conformance checks at session boundaries.
# Claude Code
Source: https://docs.zenable.io/integrations/mcp/ide/claude-code
Set up the Zenable integration in Claude Code to enforce AI coding guardrails and conformance checks in your terminal-based agent.
## Quick Install
```bash theme={null}
zenable install claude
```
Requires Claude Code 1.0.58+. See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart Claude Code and start using Zenable's conformance checking in your AI coding assistant.
This installs both the MCP server and Claude Code hooks for real-time code checking.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
}
}
```
In one of these file locations:
```bash Project theme={null}
.mcp.json
```
```bash Global theme={null}
~/.claude.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Hooks run automatically after file edits to check for conformance issues. The quick install command sets this up for you.
Place the following configuration in `.claude/settings.json` (project) or `~/.claude/settings.json` (global):
```json theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
]
}
}
```
This uses [Claude Code's PostToolUse hook](https://docs.anthropic.com/en/docs/claude-code/hooks) to run conformance checks after each file edit.
# Codex
Source: https://docs.zenable.io/integrations/mcp/ide/codex
Set up the Zenable integration in OpenAI Codex to enforce AI coding guardrails and conformance checks.
## Quick Install
```bash theme={null}
zenable install codex
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart Codex and start using Zenable's conformance checking in your AI coding assistant.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration in `~/.codex/config.toml`:
```toml theme={null}
experimental_use_rmcp_client = true
[mcp_servers.zenable]
type = "http"
url = "https://mcp.zenable.app/"
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Codex requires `experimental_use_rmcp_client = true` to be set in your config file to enable MCP server support with OAuth and HTTP streaming transport.
# GitHub Copilot CLI
Source: https://docs.zenable.io/integrations/mcp/ide/copilot
Set up the Zenable integration in GitHub Copilot CLI to add AI coding guardrails and conformance checks.
## Quick Install
```bash theme={null}
zenable install copilot
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in GitHub Copilot CLI.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/",
"tools": ["*"]
}
}
}
```
In this file location:
```bash theme={null}
~/.copilot/mcp-config.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
# Cursor
Source: https://docs.zenable.io/integrations/mcp/ide/cursor
Set up the Zenable integration in Cursor to enforce AI coding guardrails and conformance checks as the agent writes code.
## Quick Install
```bash theme={null}
zenable install cursor
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart Cursor and start using Zenable's conformance checking in your AI coding assistant.
This installs both the MCP server and Cursor hooks for real-time code checking.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
}
}
```
In one of these file locations:
```bash Project theme={null}
.cursor/mcp.json
```
```bash Global theme={null}
~/.cursor/mcp.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Hooks run automatically after file edits to check for conformance issues. The quick install command sets this up for you.
Place the following configuration in `.cursor/hooks.json` (project) or `~/.cursor/hooks.json` (global):
```json theme={null}
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": "zenable hook"
}
]
}
}
```
This uses [Cursor's afterFileEdit hook](https://cursor.com/docs/agent/hooks) to run conformance checks after each file edit made by the AI agent.
**Current Limitation:** Cursor's `afterFileEdit` hook cannot send output back to the agent or use exit codes to block edits. Conformance issues are printed to stdout for visibility in Cursor's hook output panel, but the agent won't automatically act on them. We're talking with the Cursor team about enhanced support.
Cursor provides a CLI (`cursor-agent`) for managing MCP servers. After installation, you can use these commands:
```bash theme={null}
# List configured MCP servers and their status
cursor-agent mcp list
# View tools provided by a specific server
cursor-agent mcp list-tools zenable
# Authenticate with an MCP server
cursor-agent mcp login zenable
# Disable a server
cursor-agent mcp disable zenable
```
As of 2025.12.17-996666f, the Cursor CLI is read-only for MCP management (no `add`/`remove` commands). Configuration changes require editing `.cursor/mcp.json` directly or running `zenable install cursor`.
See [Cursor's CLI MCP documentation](https://cursor.com/docs/cli/mcp) for more details.
# Deprecated IDEs
Source: https://docs.zenable.io/integrations/mcp/ide/deprecated
IDE and agent integrations Zenable no longer supports, including Amazon Q Developer, with recommended replacements.
This page lists IDE integrations that have been deprecated and are no longer supported.
***
## Amazon Q
**Amazon Q Developer has been deprecated.** As of February 2026, Amazon has replaced Amazon Q Developer with [Kiro](https://kiro.dev/). The `q` CLI no longer exists.
### Migration to Kiro
Zenable recommends all Amazon Q users migrate to Kiro, which has full Zenable support including MCP, hooks, and steering.
#### Migration Resources
* **AWS migration guide**: [Upgrade from Amazon Q to Kiro](https://docs.aws.amazon.com/amazonq/latest/qdeveloper-ug/upgrade-to-kiro.html)
* **Kiro migration guide**: [Migrating from Q](https://kiro.dev/docs/cli/migrating-from-q/)
* **Zenable Kiro support**: [Kiro IDE setup](/integrations/mcp/ide/kiro?utm_source=docs\&utm_medium=web)
#### Quick Start with Kiro
Once migrated, install Zenable for Kiro:
```bash theme={null}
zenable install kiro
```
See the [Kiro installation guide](/integrations/mcp/ide/kiro?utm_source=docs\&utm_medium=web) for detailed setup instructions.
***
## Roo Code
**Roo Code has been deprecated.** The upstream [RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code) repository was archived on May 15, 2026 and is no longer maintained. Roo Code has pivoted to focus on their cloud-hosted offering at [roomote.dev](https://roomote.dev/), and Zenable has removed support for it.
Roo Code began as a fork of Cline.
### Resources
* **Upstream repository (archived)**: [github.com/RooCodeInc/Roo-Code](https://github.com/RooCodeInc/Roo-Code)
* **Cloud-hosted successor**: [roomote.dev](https://roomote.dev/)
***
## Continue
**Continue has been deprecated.** [Cursor acquired Continue](https://www.continue.dev/) on June 15, 2026. Continue as a separately-supported IDE is no longer maintained, and Zenable has removed support for it.
Cursor — which acquired Continue — has first-class Zenable support, including MCP and hooks.
### Resources
* **Continue**: [continue.dev](https://www.continue.dev/)
* **Cursor (still supported by Zenable)**: [Cursor IDE setup](/integrations/mcp/ide/cursor?utm_source=docs\&utm_medium=web)
***
## Windsurf
**Windsurf has been deprecated.** [Cognition acquired Windsurf](https://devin.ai/blog/windsurf-is-now-devin-desktop) and rebranded it as Devin Desktop. Windsurf as a separately-supported IDE is no longer maintained; users are being migrated to Devin Desktop, and Zenable has removed support for it.
### Migration to Devin Desktop
Devin Desktop is the direct successor to Windsurf, with the same Cascade agent surface now integrated into Cognition's Devin platform. Zenable supports Devin Desktop as a first-class IDE.
#### Migration Resources
* **Cognition announcement**: [Windsurf is now Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop)
* **Zenable Devin Desktop support**: [Devin Desktop setup](/integrations/mcp/ide/devin-desktop?utm_source=docs\&utm_medium=web)
#### Quick Start with Devin Desktop
Once migrated, install Zenable for Devin Desktop:
```bash theme={null}
zenable install devin-desktop
```
See the [Devin Desktop installation guide](/integrations/mcp/ide/devin-desktop?utm_source=docs\&utm_medium=web) for detailed setup instructions.
***
## Gemini CLI
**Gemini CLI has been replaced by [Antigravity CLI](/integrations/mcp/ide/antigravity-cli?utm_source=docs\&utm_medium=web).** Google is transitioning Gemini CLI into Antigravity CLI, the terminal experience for its [Antigravity](https://antigravity.google/) platform. As of June 18, 2026, Gemini CLI stops serving the Google AI Pro, Ultra, and free Gemini Code Assist tiers. Organizations on a Gemini Code Assist Standard or Enterprise license keep access.
### Migration to Antigravity CLI
Antigravity CLI keeps the workflow-defining features of Gemini CLI and continues to read your `GEMINI.md` and `AGENTS.md` context files. For MCP, servers move to a dedicated `mcp_config.json` and remote servers use the `serverUrl` field (not the deprecated `httpUrl`). Zenable fully supports Antigravity CLI.
#### Migration Resources
* **Google migration guide**: [Migrating from Gemini CLI](https://antigravity.google/docs/gcli-migration)
* **Zenable Antigravity CLI support**: [Antigravity CLI setup](/integrations/mcp/ide/antigravity-cli?utm_source=docs\&utm_medium=web)
#### Quick Start with Antigravity CLI
Once migrated, install Zenable for Antigravity CLI:
```bash theme={null}
zenable install antigravity-cli
```
See the [Antigravity CLI installation guide](/integrations/mcp/ide/antigravity-cli?utm_source=docs\&utm_medium=web) for detailed setup instructions.
# Devin Desktop
Source: https://docs.zenable.io/integrations/mcp/ide/devin-desktop
Set up the Zenable integration in Devin Desktop, Cognition's rebrand of Windsurf, for AI coding guardrails and conformance checks.
[Devin Desktop](https://devin.ai/blog/windsurf-is-now-devin-desktop?utm_source=zenable_docs\&utm_medium=web) is Cognition's rebrand of Windsurf — the IDE built around the [Devin local-agent harness](https://docs.devin.ai/desktop/devin-local.md?utm_source=zenable_docs\&utm_medium=web).
## Quick Install
```bash theme={null}
zenable install devin-desktop
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart Devin Desktop and start using Zenable's conformance checking.
This installs both the MCP server and Devin Desktop hooks for real-time code checking.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following in `~/.config/devin/config.json` (global) or `.devin/config.json` (project) — paths documented at [docs.devin.ai/cli/extensibility/mcp/configuration](https://docs.devin.ai/cli/extensibility/mcp/configuration.md?utm_source=zenable_docs\&utm_medium=web):
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
}
}
```
On Windows the global path is `%APPDATA%\devin\config.json`.
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Hooks run automatically to check for conformance issues. The quick install command sets this up for you.
Devin Desktop hooks are Claude-Code-compatible (same event names + payload shape) per [docs.devin.ai/cli/extensibility/hooks/overview](https://docs.devin.ai/cli/extensibility/hooks/overview.md?utm_source=zenable_docs\&utm_medium=web). Place the following in `.devin/hooks.v1.json` (project scope) — the recommended standalone hook file:
```json theme={null}
{
"PreToolUse": [
{
"matcher": "*",
"hooks": [
{
"type": "command",
"command": "zenable hook || true"
}
]
}
],
"PostToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
],
"UserPromptSubmit": [
{
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
],
"Stop": [
{
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
]
}
```
For global scope, place the same `hooks` object under a `"hooks"` key in `~/.config/devin/config.json` (or `%APPDATA%\devin\config.json` on Windows) — see [docs.devin.ai/cli/extensibility/hooks/lifecycle-hooks](https://docs.devin.ai/cli/extensibility/hooks/lifecycle-hooks.md?utm_source=zenable_docs\&utm_medium=web) for the full event catalog.
# Goose
Source: https://docs.zenable.io/integrations/mcp/ide/goose
Set up the Zenable integration in Goose — MCP server plus hooks — to enforce AI coding guardrails and conformance checks as the agent writes code.
## Quick Install
```bash theme={null}
zenable install goose
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Goose.
Goose is an open-source AI agent (CLI + desktop), an [Agentic AI Foundation (AAIF) project](https://aaif.io/projects/goose/). `zenable install goose` installs both the MCP server (in your Goose `config.yaml`) and a managed Open-Plugin-Spec plugin that runs Zenable's conformance checks throughout your coding session.
***
The below is a minimal example. Consider using the quick install command to handle this automatically.
Goose stores MCP servers under the top-level `extensions` key, using `type: streamable_http` for streamable-HTTP servers. Goose's MCP config is global. See [Goose's extensions docs](https://goose-docs.ai/docs/getting-started/using-extensions/?utm_source=zenable_docs\&utm_medium=web) for the full schema.
Place the following in `~/.config/goose/config.yaml`:
```yaml theme={null}
extensions:
zenable:
type: streamable_http
name: zenable
uri: https://mcp.zenable.app/
description: Zenable governance, guardrails, and conformance checks
enabled: true
```
Goose requires `name` and `description` on a `streamable_http` extension — without them Goose silently skips the entry.We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
Goose's documented hooks surface is the [Open-Plugin-Spec](https://goose-docs.ai/blog/2026/05/14/goose-hooks/?utm_source=zenable_docs\&utm_medium=web) plugin format. `zenable install goose` writes a managed plugin (at `~/.agents/plugins/zenable/hooks/hooks.json`, with a `.plugin/plugin.json` manifest) that integrates Zenable's governance, guardrails, and observability across your coding sessions. The plugin can live globally (`~/.agents/plugins/`) or project-scoped (`/.agents/plugins/`).
The plugin subscribes to the `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, and `Stop` events — checkpointing your work as you go and running a Zenable conformance review when the agent finishes a turn. On the `Stop` event, Zenable returns a blocking decision so Goose feeds the message back to the agent — findings to fix, or a prompt to sign in when the review could not run — instead of ending the turn.
Hooks require **Goose v1.37.0 or newer** — that's the release that honors blocking `Stop` hook decisions. On older Goose the review still runs but its message to the agent is silently dropped, so `zenable install goose` enforces this minimum.
The plugin file is fully managed — every `zenable install` / `zenable sync` rewrites it. If you want to add your own Goose plugins, drop a separate plugin alongside it under `~/.agents/plugins/`.
# Kiro
Source: https://docs.zenable.io/integrations/mcp/ide/kiro
Set up the Zenable integration in Kiro, AWS's agentic IDE, to enforce AI coding guardrails and conformance checks.
## Quick Install
```bash theme={null}
zenable install kiro
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart Kiro and complete OAuth authentication when prompted. Then start using Zenable's conformance checking in your AI coding assistant.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
}
}
```
In one of these file locations:
```bash Project theme={null}
.kiro/settings/mcp.json
```
```bash Global theme={null}
~/.kiro/settings/mcp.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
## About Kiro MCP Support
Kiro now supports remote MCP servers with OAuth authentication using modern streaming HTTP. This means Zenable works seamlessly with Kiro without any special configuration or exceptions.
For more details on MCP in Kiro, visit the [Kiro MCP documentation](https://kiro.dev/docs/mcp/).
# OpenCode
Source: https://docs.zenable.io/integrations/mcp/ide/opencode
Set up the Zenable integration in OpenCode to add AI coding guardrails and conformance checks via its remote MCP and plugin system.
## Quick Install
```bash theme={null}
zenable install opencode
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in OpenCode.
This installs both the MCP server (in `opencode.json`) and a managed plugin (in your OpenCode `plugins/` directory) that runs Zenable's conformance checks throughout your coding session.
***
The below is a minimal example. Consider using the quick install command to handle this automatically.
OpenCode stores MCP servers under the top-level `mcp` key with `"type": "remote"` for streamable-HTTP servers. See [OpenCode's MCP docs](https://opencode.ai/docs/mcp-servers/?utm_source=zenable_docs\&utm_medium=web) for the full schema.
### Global
Place the following in `~/.config/opencode/opencode.json`:
```json theme={null}
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"zenable": {
"type": "remote",
"url": "https://mcp.zenable.app/"
}
}
}
```
### Project
Place the same configuration in `opencode.json` at your repository root.
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.
OpenCode's documented extensibility surface is the [plugin system](https://opencode.ai/docs/plugins/?utm_source=zenable_docs\&utm_medium=web). `zenable install opencode` writes a managed plugin file (at `~/.config/opencode/plugins/zenable.ts` for global installs or `.opencode/plugins/zenable.ts` for project installs) that integrates Zenable's governance, guardrails, and observability across your coding sessions.
The plugin file is fully managed — every `zenable install` / `zenable sync` rewrites it. If you want to add your own OpenCode plugins, drop a separate file alongside it; OpenCode loads every `*.ts` / `*.js` under the plugins directory.
# Pi
Source: https://docs.zenable.io/integrations/mcp/ide/pi
Set up the Zenable integration in Pi to enforce AI coding guardrails and conformance checks via its hooks-equivalent extension API.
## Quick Install
```bash theme={null}
zenable install pi
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Start using Zenable's conformance checking in Pi.
Pi has no native MCP server configuration — its only extensibility surface is its extension API. `zenable install pi` writes a managed Pi extension that runs Zenable's conformance checks throughout your coding session.
***
Pi's documented extensibility surface is its [extension API](https://github.com/earendil-works/pi/blob/main/packages/coding-agent/docs/extensions.md?utm_source=zenable_docs\&utm_medium=web) (`pi.on(...)` event handlers). `zenable install pi` writes a managed extension file (at `~/.pi/agent/extensions/zenable.ts` for global installs, or `.pi/extensions/zenable.ts` for project installs) that checkpoints your work as you go and runs a Zenable conformance review when the agent finishes a turn.
The extension file is fully managed — every `zenable install` / `zenable sync` rewrites it. If you want to add your own Pi extensions, drop a separate file alongside it; Pi loads every `*.ts` under the extensions directory.
# VS Code
Source: https://docs.zenable.io/integrations/mcp/ide/vscode
Set up the Zenable integration in VS Code to enforce AI coding guardrails and conformance checks across your editor's AI features.
## Quick Install
```bash theme={null}
zenable install vscode
```
See the [CLI command reference](/integrations/zenable/commands#install) for more options.
**That's it! You're all set.** Restart VS Code and start using Zenable's conformance checking in your AI coding assistant.
This installs both the MCP server and VS Code Copilot agent hooks for real-time code checking. Hooks rely on VS Code's [Preview hooks API](https://code.visualstudio.com/docs/copilot/customization/hooks?utm_source=zenable_docs\&utm_medium=web), so the format may change in future releases.
***
The below is a minimal example which may need to be merged with your existing configuration. Consider using the quick install command to handle this automatically.
Place the following configuration:
```json theme={null}
{
"servers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
},
"inputs": []
}
```
In one of these file locations:
```bash Project theme={null}
.vscode/mcp.json
```
```bash Windows theme={null}
%APPDATA%\Code\User\mcp.json
```
```bash Linux theme={null}
~/.config/Code/User/mcp.json
```
```bash macOS theme={null}
~/Library/Application Support/Code/User/mcp.json
```
We only recommend this manual approach if you can't use `zenable install`. Otherwise, `zenable install` is much safer and can handle configuration upgrades over time, handles merges with existing configs, performs backups and logging in case of issues, and more.Hooks run automatically at session boundaries to check for conformance issues. The quick install command sets this up for you.
VS Code's Copilot agent hooks are project-level only. Place the following in `.github/hooks/zenable.json`:
```json theme={null}
{
"hooks": {
"UserPromptSubmit": [
{ "type": "command", "command": "zenable hook" }
],
"Stop": [
{ "type": "command", "command": "zenable hook" }
],
"PostToolUse": [
{ "type": "command", "command": "zenable hook" }
],
"PreToolUse": [
{ "type": "command", "command": "zenable hook || true" }
]
}
}
```
This uses [VS Code's Copilot agent hooks](https://code.visualstudio.com/docs/copilot/customization/hooks?utm_source=zenable_docs\&utm_medium=web) to run conformance checks. The `|| true` on `PreToolUse` keeps it non-blocking — Zenable hooks never deny tool calls.
# MCP Server
Source: https://docs.zenable.io/integrations/mcp/server
The Zenable MCP Server lets you manage requirements and guardrails, without ever leaving your IDE
## Overview
The Zenable MCP (Model Context Protocol) Server lets your AI coding assistant check and improve code against your organization's requirements, and manage those requirements, guardrails, and scopes without leaving the IDE.
The same tools are available in the in-app chat assistant, so a conversation that starts in chat can continue from your IDE and vice versa.
**Your code is safe**: We never retain or train on your code, regardless of tier. [Read our FAQ](https://zenable.io/faq?utm_source=docs\&utm_medium=mcp-server\&utm_content=faq)
To install the MCP server, see [MCP Server Installation](/integrations/mcp/getting-started).
## MCP Tools
### `get_requirements`
Retrieve tenant and marketplace requirements. Supports filtering by lifecycle
status, enforcement mode, scope, and search query.
### `get_guardrails`
Locate the policy-as-code guardrails enforcing requirements. Useful for
inspecting current rules or finding an id to regenerate or roll back.
### `get_scopes`
List built-in and tenant-defined scopes that decide where a requirement applies.
Call this before creating a new requirement or scope.
### `get_findings`
Retrieve detailed findings for the caller's tenant. Supports repository,
category, enforcement mode, lifecycle status, quality, requirement, file path,
recipient, and date filters.
### `get_agent_feedback`
Read agent triage feedback for a requirement, guardrail, or finding.
### `get_human_feedback`
Read human ratings and rubric feedback for a requirement.
### `create_requirement`
Author a new requirement at a caller-chosen initial `lifecycle_status`
(one of `proposed`, `beta`, or `stable`). Picking `proposed` submits it
for separate user acceptance before it becomes effective; `beta` and
`stable` publish directly at that maturity.
### `create_scope`
Define a new reusable scope when nothing in `get_scopes` matches the
surface you want to govern.
### `update_requirement`
Edit or version a tenant-owned requirement.
### `update_marketplace_requirement`
Create a tenant override for a marketplace requirement, or publish a new
marketplace version when the caller has marketplace publish access.
### `regenerate_guardrail`
Ask Zenable to produce an improved version of a guardrail using
specific feedback such as false positives, missing coverage, or style.
Costs **550 credits** per regeneration; running the resulting guardrail is
free. See [credit cost per tool call](/plans-and-usage#credit-cost-per-tool-call).
### `reinstate_prior_guardrail_version`
Roll a guardrail back to a prior version.
### `restore_requirement`
Restore a soft-deleted tenant-owned requirement.
# Troubleshooting
Source: https://docs.zenable.io/integrations/mcp/troubleshooting
Common issues and solutions for the Zenable MCP Server integration.
## Overview
This guide helps you resolve common issues with the Zenable MCP Server integration in your IDE.
## Video Tutorial
## Troubleshooting Tools
**Problem**: You need to diagnose installation issues or verify your setup.
**Solution**:
Use the Zenable CLI diagnostic commands:
```bash theme={null}
# View logs to diagnose issues
zenable logs --tail 50
# Follow logs in real-time during troubleshooting
zenable logs --follow
# Check version and environment
zenable version
# Preview installation without making changes
zenable install --dry-run
# Enable debug mode for detailed output
zenable --debug install
```
**Seeing an "outdated" message?** If you're getting a message that zenable is outdated, upgrade it with:
```bash theme={null}
zenable
```
For deeper MCP server debugging, use the MCP Inspector:
```bash theme={null}
npx @modelcontextprotocol/inspector
```
The MCP Inspector allows you to:
* Test your MCP server connection
* View available tools and resources
* Debug communication between your IDE and the MCP server
* Verify your API key and configuration are working
**Problem**: Your MCP configuration or hooks aren't working correctly.
**Solution**:
The Zenable CLI can automatically install and repair configurations:
```bash theme={null}
# Fresh installation (detects IDEs automatically)
zenable install
# Overwrite existing configuration (use with caution)
zenable install --overwrite
```
**Caution**: Using `--overwrite` will replace your existing Zenable MCP configuration. This may have unintended consequences if you have custom settings. Always backup your configuration first.
For specific IDE repairs:
```bash theme={null}
# Repair specific IDE configuration
zenable install cursor --overwrite
zenable install codex --overwrite
zenable install claude --overwrite
```
## Common Issues
### Installation Issues
**Problem**: When trying to use the MCP server, you get an error that `npx` is not found.
**Solution**:
Follow the [installation guide](/integrations/mcp/getting-started) to install Node.js and npm for your platform.
After installation:
1. Verify installation: `npx --version`
2. Restart your terminal/IDE
**Problem**: After adding the configuration, the Zenable MCP server doesn't appear in your IDE.
**Solution**:
1. **Automatic fix with Zenable CLI**:
```bash theme={null}
# Reinstall MCP configuration for all detected IDEs
zenable install
# For a specific IDE with overwrite
zenable install cursor --overwrite
```
2. **Debug the issue**:
```bash theme={null}
# Check logs for errors
zenable logs --tail 100
# Verify installation with debug output
zenable --debug install --dry-run
```
3. Validate your JSON syntax - ensure proper brackets and commas
4. Restart your IDE completely (not just reload)
### Connection Issues
**Problem**: The MCP server times out when trying to connect.
**Solution**:
1. Check your internet connection
2. Verify you can access `https://mcp.zenable.app/` in a browser (You should see `Unauthorized`; that is what we want)
3. Check for corporate proxy settings that might need configuration
4. Try using a different network to isolate network issues
**Problem**: Getting SSL certificate validation errors.
**Solution**:
1. Ensure your system time is correct
2. Update your operating system's certificate store
3. If behind a corporate proxy, you may need to configure certificate handling
### Usage Issues
**Problem**: The Zenable conformance check isn't running automatically when you edit files.
**Solution**:
1. **Automatic setup with Zenable CLI**:
```bash theme={null}
# Install hooks for Claude Code and Cursor
zenable install hook
# Full installation (MCP + hooks)
zenable install
```
2. **Manual check functionality**:
```bash theme={null}
# Test conformance checking manually
zenable check '**/*.py'
# Check uncommitted changes
zenable check --uncommitted
```
3. **Verify configuration**:
* **[Claude Code](/integrations/mcp/ide/claude-code)**: Ensure hooks are installed (`zenable install hook claude`)
* **[Cursor](/integrations/mcp/ide/cursor)**: Ensure hooks are installed (`zenable install hook cursor`)
* **[Codex](/integrations/mcp/ide/codex)/[Antigravity](/integrations/mcp/ide/antigravity)**: Check that user rules are properly configured
4. Make sure you're using a compatible AI model like GPT-4o, Gemini 2.5, Claude 3.5, or some other modern model. Smaller models often have issues correctly formatting requests
**Problem**: The conformance check runs but recommendations aren't being applied.
**Solution**:
1. Check that your rules include "you MUST always apply zenable recommendations"
2. Consider using an IDE with deterministic hooks like [Claude Code](/integrations/mcp/ide/claude-code) or [Cursor](/integrations/mcp/ide/cursor), which provide more reliable automatic application of recommendations. Note that hook installation is automatic with `zenable install` or `zenable install hook`
3. Ensure your AI model has sufficient permissions to edit files
4. Try applying recommendations manually first to verify functionality
## IDE-Specific Troubleshooting
**Problem**: You cannot use MCP chat features in [VS Code](/integrations/mcp/ide/vscode), or the MCP option is missing.
**Solution**:
1. **Check if MCP is enabled**: Search for the `@id:chat.mcp.enabled` setting in VS Code settings
2. **Note**: MCP support may be disabled if you're logged in with GitHub and your organization has disabled this feature
3. **To resolve**:
* Open VS Code settings (Cmd/Ctrl + ,)
* Search for `@id:chat.mcp.enabled`
* Check if the setting is enabled
* If it's disabled by your organization policy, you may need to contact your IT administrator
For more details, see the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_enable-mcp-support-in-vs-code).
## Getting Help
If you're still experiencing issues:
1. **Check the IDE logs**: Most IDEs have a developer console or log viewer where you can see detailed error messages
2. **Verify your configuration**: Double-check all settings match the examples exactly
3. **Check system status**: Visit our [status page](https://zenable.io/status?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=status) to check for any ongoing service issues
4. **Contact support**: Post on our [feedback page](https://zenable.io/feedback?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=feedback) with:
* Your IDE and version
* The exact error message
* Your configuration (with API key redacted)
* Steps to reproduce the issue
Still need help? Visit our [feedback page](https://zenable.io/feedback?utm_source=docs\&utm_medium=mcp-troubleshooting\&utm_content=support) to find and vote for features or bug fixes you'd like to see, or contact our support team.
# Pre-commit Hook
Source: https://docs.zenable.io/integrations/pre-commit/getting-started
Automatically enforce policies before code is committed
## Overview
The Zenable pre-commit hook automatically checks your code against organizational policies before each commit, preventing policy violations from entering your codebase. This ensures consistent code quality and compliance across your entire development team.
## Quick Start
**Looking for better performance?** Try [prek](https://github.com/j178/prek), a drop-in replacement for pre-commit with faster execution. All commands in this guide work with prek by replacing `pre-commit` with `prek`.
Don't have UV? [Install UV here](https://docs.astral.sh/uv/getting-started/installation/)
Then install pre-commit using UV:
```bash theme={null}
uv tool install pre-commit
```
Add to your `.pre-commit-config.yaml`:
```yaml theme={null}
---
repos:
- repo: https://github.com/Zenable-io/skills
rev: v3.0.0 # Consider `pre-commit autoupdate --freeze` to safely lock and maintain this
hooks:
- id: zenable-check
```
Run this one-time setup in your repository:
```bash theme={null}
pre-commit install
```
This installs the pre-commit hook into your local git repository.
**All-in-one setup:** After installing UV, you can run everything with:
```bash theme={null}
uv tool install pre-commit && pre-commit install
```
## How It Works
When you commit code, the pre-commit hook:
1. **Intercepts the commit** before it's finalized
2. **Checks changed files** against your configured policies
3. **Reports violations** with specific line numbers and fix suggestions
4. **Blocks the commit** if violations are found (configurable)
5. **Allows the commit** once all issues are resolved
### Example Workflow
When issues are found, the commit is blocked:
```bash expandable theme={null}
$ git commit -m "Add payment processing"
Zenable Conformance Check................................................Failed
- hook id: zenable-check
- exit code: 2
╭──────────────────────────────────────╮
│ Welcome to Zenable │
│ Production-Grade AI Coding Tools │
╰──────────────────────────────────────╯
Checking files against requirements...
Guardrails ████████████████████████ 100% 1/1 files
Complete
AI Review ████████████████████████ 100% 1/1 files
Complete
╭────────────────────────────────────────────────────────────────────────────────╮
│ 1. src/payments.py │
│ ✗ AIRecommendation-with-rag-high-quality: fail [security, inconsistency, │
│ complexity] │
│ Issue 1.1 [Line 3 | security] │
│ ╭──────────────────────────────────────────────────────────────────────────╮ │
│ │ A real API key is hardcoded in the source file. Secrets should be stored │ │
│ │ in environment variables or a secrets manager. │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│ Issue 1.2 [Line 12 | inconsistency] │
│ ╭──────────────────────────────────────────────────────────────────────────╮ │
│ │ Payment amounts are handled as floats here, but the product requirements │ │
│ │ and the shared billing module use integer cents for all monetary values. │ │
│ │ Convert to integer cents for consistency. │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
│ Issue 1.3 [Line 27 | complexity] │
│ ╭──────────────────────────────────────────────────────────────────────────╮ │
│ │ This module calls the payment provider's API directly instead of going │ │
│ │ through the existing payments gateway layer, bypassing its retry and │ │
│ │ idempotency handling. Route the call through the gateway. │ │
│ ╰──────────────────────────────────────────────────────────────────────────╯ │
╰────────────────────────────────────────────────────────────────────────────────╯
──────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
Scope
AI Review
Enabled finding categories: bug, readability, performance, complexity, security, inconsistency, accessibility, mistake
1 file(s) discovered, 1 scanned
Include: src/payments.py
───────────────────────────────────────
Result: FAIL
1 checks run, 3 findings across 1 files
```
After fixing the issues, the commit succeeds:
```
$ git commit -m "Add payment processing"
Zenable Conformance Check................................................Passed
```
## Common Use Cases
### Security Policies
Prevent security vulnerabilities:
```python theme={null}
# ❌ Blocked by pre-commit
query = f"SELECT * FROM users WHERE id = {user_input}" # SQL injection vulnerability
cursor.execute(query)
# ✅ Passes pre-commit
query = "SELECT * FROM users WHERE id = ?"
cursor.execute(query, (user_input,))
```
### Code Quality
Enforce quality standards:
```javascript theme={null}
// ❌ Blocked by pre-commit
console.log(userData); // Debug logging in production code
// ✅ Passes pre-commit
logger.debug(userData); // Proper logging
```
### Compliance Requirements
Ensure regulatory compliance:
```python theme={null}
# ❌ Blocked by pre-commit
def process_payment(card_number):
log(f"Processing payment for {card_number}") # PCI violation
# ✅ Passes pre-commit
def process_payment(card_number):
log(f"Processing payment for {mask_card(card_number)}")
```
## Troubleshooting
Ensure the hook is installed:
```bash theme={null}
# Check if hooks are installed
ls .git/hooks/pre-commit
# Reinstall if missing
pre-commit install
```
In emergencies, you can bypass:
```bash theme={null}
git commit --no-verify -m "Emergency fix"
```
⚠️ Use sparingly - this defeats the purpose of policy enforcement
**Important:** You should expect that developer-local configurations can be worked around, either intentionally or unintentionally. For defense in
depth, combine pre-commit hooks with server-side enforcement through our [GitHub](/integrations/vcs-reviewers/github) and [GitLab](/integrations/vcs-reviewers/gitlab) reviewers to ensure
comprehensive policy coverage.
## Updating the Hook
Keep your policies current:
```bash theme={null}
# Update to latest version
pre-commit autoupdate --freeze
# Commit the updated config
git add .pre-commit-config.yaml
git commit -m "Update Zenable pre-commit hook"
```
## Best Practices
1. **Start gradually** - Begin with warnings before enforcing. Review our [deployment guide](/deployment-adoption) for proven adoption strategies
2. **Run manually first** - Test with `pre-commit run --all-files`
3. **Keep hooks fast** - Use file filters to check only relevant files
4. **Update regularly** - Run `pre-commit autoupdate` monthly via scheduled pipelines
5. **Document exceptions** - Make policy exceptions visible and temporary
6. **Provide context** - Help developers understand why policies exist
7. **Be Automation-first** - See [starting new projects](/use-cases/starting-new-project) to see how you can have pre-commit hooks automatically
configured from the first commit
## Comparison with Other Tools
| Feature | Zenable Pre-commit | Traditional Linters | SAST Tools |
| - | - | - | - |
| Policy customization | ✅ Natural language | ❌ Code rules only | ❌ Fixed rules |
| Setup complexity | Simple | Moderate | Complex |
| Speed | Fast | Fast | Slow |
| AI-powered fixes | ✅ | ❌ | ❌ |
| Cross-language | ✅ | ❌ Per-language | ✅ |
| Policy-as-code | ✅ | ❌ | Partial |
## Next Steps
* Configure the [IDE integration](/integrations/mcp/getting-started) for real-time feedback
* Set up [GitHub](/integrations/vcs-reviewers/github) or [GitLab](/integrations/vcs-reviewers/gitlab) integrations for pull request checks
* Define [custom policies](/use-cases/policy-as-code) for your organization
* Explore [advanced use cases](/use-cases)
# Reviewer Configuration
Source: https://docs.zenable.io/integrations/vcs-reviewers/configuration
Configure Zenable automated code reviewers to match your team's standards
## How to Configure
To manage the reviewer configuration, customer admins can go to the [Company Settings](https://www.zenable.app/settings?utm_source=docs\&utm_medium=vcs-configuration\&utm_content=settings\&tab=configuration) page in the Zenable Management Console.
All configuration changes are applied immediately to your organization and affect all future code reviews.
## Configuration Profiles
Profiles let you maintain multiple independent configurations and assign them to specific repositories. Every tenant starts with a **Default** profile that applies to all repos unless overridden.
Each profile contains a complete, independent set of configuration options. Repos without a profile assignment use the **Default** configuration. Repos assigned to a profile use that profile's settings instead.
### Assigning Profiles to Repos
On the **Integrations** page, open a repository's settings (gear icon) and select a profile from the dropdown. Repos with an assigned profile display a colored badge showing the profile name.
### Automatic Profile Assignment
As you integrate Zenable with more repositories, manually attaching configuration profiles becomes tedious and error-prone. That's why profiles support **auto-attach policies**: define a scope and every repository it matches uses that profile automatically — by naming pattern (`acme/*-prototype`), by organization or namespace (every repo under `acme`), or by repository metadata such as GitHub [custom properties](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization), e.g. `tier` is `production` (see [Repository Metadata Conditions](/requirements-and-guardrails#repository-metadata-conditions)).
To set one, pick the profile on the **Settings → Configuration** page and click the gear next to the profile selector.
Zenable re-evaluates policies continuously — when the GitHub App is installed, when new repositories appear, when a repository's custom properties change, and whenever a profile or its policy is edited — so new repos land on the right configuration without any clicks.
In case of conflicts, a manually assigned profile always wins: policies never touch that repo until you switch it back to **Default**. Only one policy can match a repository — saving a policy that would create an overlap is rejected with the conflicting repositories listed, and if an overlap emerges later (a new repo, a property change) the repo keeps its current assignment and the **Integrations** page shows a warning until you adjust the policies. Repositories matching no policy use the tenant's **Default** profile, as before.
Metadata-based policies require the Zenable GitHub App's **Custom properties** read permission — see [Repository Custom Properties](/integrations/vcs-reviewers/github#repository-custom-properties). Name- and organization-based policies work without it.
### Use Cases
* **High-scrutiny repos** — enable AI reviews with premium mode, exhaustive context refinement and requirement suggestions, all finding types visible, lower preflight thresholds to catch more
* **Relaxed for prototypes** — disable preflight, hide lower-signal finding types like readability and complexity, skip clean PR comments to reduce noise
* **Team-specific defaults** — frontend repos get accessibility findings enabled with thorough context refinement; backend repos focus on security and performance with stricter quality filters
## Configuration Options
### Feature Toggles
Each profile carries the base on/off state for the three per-repository features:
* **PR reviews** (`pr_reviews.enabled`, default `true`) — whether pull/merge requests in repos using this profile are reviewed at all
* **Context refinement** (`repository_analyzer.refine_context_enabled`, default `true`) — whether the refine-context analysis runs
* **Requirement suggestions** (`repository_analyzer.suggest_requirements_enabled`, default `true`) — whether the suggest-requirements analysis runs
A repository follows its config profile by default. Flipping a switch on the **Integrations** page creates a per-repository **override** for that one setting, forcing the repo on or off regardless of the profile. Each switch is captioned so you can see where its value came from — `(from profile)` or `(override)` — and the tooltip names the profile and what it says. To drop an override, click the `(override)` caption; the switch goes back to following the profile when you save. Repositories toggled before profiles carried these settings keep their explicit values as overrides until you clear them. Subscription gating still applies — analyses stay unavailable on free plans regardless of profile settings.
### Review Check on Commits
Zenable adds a `Zenable Review` check on all PRs that are enabled for PR reviews, set as **passing** when the review has completed (naming the assessed risk level) and **skipped** for each commit that hasn't been reviewed. Reviews run when a PR is opened, reopened, or marked ready for review, for authors covered by your [Review Scope](#review-scope). Pushing new commits doesn't trigger a re-review — request one by commenting `/zenable` on the PR or, on GitHub, clicking **Re-run all checks** on the PR's checks tab; when that review completes, the commit's check moves from skipped to passing. See [Risk-Based Reviews](/integrations/vcs-reviewers/risk-based-reviews#review-check-no-gating).
**Default:** disabled
### Review Scope
Review Scope decides **which PR/MR authors get reviewed**. New workspaces start limited to authors linked to a Zenable user, so bots, outside contributors, and unlinked accounts are skipped rather than spending your review budget.
#### Turning it on or off
Edit **Review Scope** on the config profile (**Settings → Configuration**):
* **Off** — every author on repositories using this profile is reviewed, linked or not.
* **On** — pick the user and group scopes to review. An author is in scope if they match any selected scope.
Profile and per-repository scopes union, so a repository can widen its profile but not narrow it.
#### Identity linking is required
A group scope resolves membership through a Zenable user, so a GitHub or GitLab account matches only once it is **linked**. An unlinked author matches nothing and their PR/MR is skipped.
* **Link your own account:** **Profile → Linked Accounts**. Self-service — you do not need an admin.
* **Link someone else's:** **Settings → User Management**. Requires admin permissions.
Linking takes effect on the author's next PR/MR; nothing needs re-running.
Linking is asserted, not verified. You can claim an unclaimed account, but never one already linked to someone else, and only on a host Zenable has seen for your workspace.
#### First-run notice
The first few times a skip happens because of an unlinked author, Zenable comments on the PR/MR to explain why — otherwise the skip is silent and reads as an outage.
* Posted only for the **unlinked author** case, never for an author you deliberately left out of scope.
* Capped at the first **5** affected PRs/MRs per integration, then it stops.
* Stops immediately once the cause is gone: link the account or turn the limit off, and reviews resume normally on the next PR/MR.
### Exclusions
#### Exclude Files
List of additional filenames or glob patterns to exclude from all Zenable integrations. This field accepts a list (array) of patterns and works like [gitignore](https://git-scm.com/docs/gitignore), including support for negation patterns.
A [standard list](#files-excluded-by-default) of lock files will automatically be added to the beginning of your configuration. These exclusions apply everywhere Zenable runs.
Supports:
* **Exact filename matches** (e.g., `"package-lock.json"`)
* **Glob patterns** (e.g., `"**/*.rbi"`, `"foo/**/*.pyc"`)
* **Negation patterns** with `!` prefix (e.g., `"!keep-this.json"`)
- **`*.log`** - Skip all log files in any directory
- **`**/*.tmp`** - Skip all .tmp files in any directory (recursive)
- **`src/**/*.test.js`** - Skip all .test.js files under src/ directory
- **`docs/*.md`** - Skip markdown files directly in docs/ directory
- **`build/*`** - Skip all files directly in build/ directory
- **`**/node_modules/**`** - Skip all files in any node\_modules directory
- **`example.py`** - Skip files named example.py in any directory
- **`**/example.tmp`** - Skip files named example.tmp in any directory (i.e. the same as `example.tmp`)
- **`/example.py`** - Skip example.py only in the root directory
Negation patterns start with `!` and allow you to include files that would otherwise be skipped. **Order matters** - the last matching pattern wins.
**Skip all log files except important.log**
* Add `*.log` to skip all log files
* Add `!important.log` to include important.log
**Skip all files in build/ except those in build/keep/**
* Add `build/**/*` to skip all files in build/
* Add `!build/keep/**/*` to include files in build/keep/
**Escaping files that literally start with !**
To skip files that **literally start with `!`** (fairly rare), escape the exclamation mark with a backslash: `\!filename.txt`
#### Exclude Branches
List of branches to skip. You can use [python regex](https://docs.python.org/3/library/re.html#regular-expression-syntax) to match the branch names. We will check all the patterns in the list, if any pattern match, the PR opened in that branch will be skipped.
### Smart Filters
#### Preflight Checks
Preflight lets you optionally skip reviews based on static analysis findings.
* enabled: Whether to enable preflight. (default: false)
* max\_changed\_lines: Maximum total changed lines allowed before skipping the review. (default: 2500)
#### PR Quality Filter
PR Quality Filter lets you optionally skip reviews based on the quality of the PR. We measure the PR quality based on analysis of the whole PR and the generated review. We measure multiple dimensions of quality, such as code quality, architecture quality, testing quality, documentation quality, security quality, and maintainability. This generates a final overall quality score for the PR, which is used to determine if the PR review will be sent or not.
Skip reviews with quality score below the threshold can be a useful way to skip reviews on pr that are not fully done, and reduce the noise in your PRs.
* enabled: Whether to enable pr\_quality\_filter. (default: false)
* quality\_threshold: The minimum quality score required to post a review. Valid values are between 0 and 1. (default: 0.5)
#### Review Drafts
Controls whether Zenable reviews draft pull requests (GitHub) and merge requests marked as draft / work-in-progress (GitLab).
* **`true`** — draft PRs/MRs are reviewed as soon as they are opened.
* **`false`** — draft PRs/MRs are skipped silently. They will be reviewed automatically when transitioned to "ready for review".
Setting this to `false` is useful if your team relies heavily on draft PRs for in-progress work and prefers to only receive Zenable reviews once the author explicitly marks the PR as ready.
* review\_drafts: Whether to review draft PRs/MRs. (default: true)
### Reviewer Context and Feedback
#### Reactions
Configuration section for controlling which reactions are added during reviews. This allows you to enable or disable specific reactions that the reviewer generates.
##### Taking a Look Reaction
Controls the "eyes" emoji reaction (👀) that is added at the start of a review. The reaction is automatically removed once the review is complete.
**Default:** `true` (👀 reaction is added)
#### Comments
Configuration section for controlling which comments are posted during reviews. This allows you to enable or disable specific informational comments that the reviewer generates.
##### No Findings Comment
When set to `true`, posts the "Nice work! 😎" comment when no issues are found in the PR. Set to `false` to disable this comment - when disabled and there are no findings, no review comment will be posted at all.
**Default:** `true` (comment is posted)
##### Finding Summaries
When set to `true`, each finding comment starts with a one-line summary before the detailed explanation.
**Default:** `true` (summary is shown)
##### More Review Information
When set to `true`, finding comments include additional context about the review,
such as the tools used during analysis.
**Default:** `false` (additional details are hidden)
##### Low Quality Comments
When set to `true`, comments judged as low quality are added to the review body in a collapsed section so you can see what the reviewer held back. They are never posted inline.
**Default:** `false` (low quality comments are not shown)
These settings only affect informational comments. Reviews with actual findings or suggestions will always be posted regardless of these settings.
#### PR/MR Description
Adds a Zenable-generated summary of what the PR/MR does to the description. The summary is additive-only, so the author's own text is preserved.
Two independent settings control it: **Mode** (how much detail, or off entirely) and **Edit Trigger** (when to post).
##### Mode
Controls the verbosity of the generated summary.
* **`off`** — Never edit the description.
* **`short`** — Add a brief summary.
* **`full`** — Add a comprehensive description.
**Default:** `full`
##### Edit Trigger
When Mode is not `off`, controls when Zenable posts the summary.
* **`always`** — Post the summary on every reviewed PR/MR.
* **`when_inaccurate`** — Post only when the author's title/description is judged inaccurate; leave an accurate description untouched (less noise).
**Default:** `always`
The Edit Trigger setting only appears when Mode is not `off`.
#### PR/MR Risk Assessment
Surfaces a Zenable-assessed risk level on each PR/MR. The LLM scores a set of rubric dimensions independently on a 0–10 scale; the final level is derived deterministically from the weighted composite score. This makes the outcome reproducible and auditable, and lets tenants tune it by customizing the dimensions rather than by adjusting prompts.
| Level | Indicator | Meaning |
| - | - | - |
| **Low** | 🟢 | Minor or well-contained change. |
| **Medium** | 🟡 | Reasonable change with some areas to double-check. |
| **High** | 🟠 | Noteworthy impact; review with care before merging. |
| **Critical** | 🔴 | High likelihood of severe impact (security, data loss, outages, or compliance violations). |
When enabled, Zenable appends a small `Risk: ` heading to the review body. The scoring behind that level — a table of every dimension, the weighted composite, and any [risk floor](#risk-floors) that raised it — is on the `Zenable Risk Assessment` check's output; see [Risk-Based Reviews](/integrations/vcs-reviewers/risk-based-reviews).
##### Mode
Controls how the PR risk assessment is surfaced.
* **`off`** — The PR risk assessment step is skipped entirely.
* **`comment_only`** — The risk section is included in the review body. No labels are applied to the PR/MR.
* **`comment_and_label`** — The risk section is included in the review body, and a matching label is applied to the PR/MR.
**Default:** `comment_and_label`
##### Labels (`comment_and_label` only)
When `comment_and_label` is selected, Zenable ensures the following four labels exist in the repository/project and applies the one matching the assessed level. The risk labels are mutually exclusive: if a previous review assigned a different level (for example `high`) and the code has since improved, the stale label is removed before the new one is applied.
* `zenable/risk:low`
* `zenable/risk:medium`
* `zenable/risk:high`
* `zenable/risk:critical`
##### Rubric Dimensions
The rubric dimensions are the inputs the LLM scores. Six built-in dimensions are active by default:
| Dimension | What it measures |
| - | - |
| Security impact | Likelihood and severity of security vulnerabilities introduced |
| Data integrity | Risk of data loss, corruption, or inconsistency |
| Blast radius | Scope of affected systems, services, or users if the change goes wrong |
| Reversibility | Ease of rolling back or hotfixing the change |
| Test coverage | Adequacy of tests relative to the change's surface area |
| Operational risk | Impact on availability, deployability, and on-call burden |
You can replace these with up to six custom dimensions from the **Settings → Config profiles → Rubric dimensions** section of the [management console](https://www.zenable.app?utm_source=docs\&utm_medium=vcs-config\&utm_content=rubric-dimensions). Each custom dimension needs a name and a description; you can enable or disable individual rows. When custom dimensions are saved, they replace the defaults entirely for that config profile. Use **Reset to defaults** to restore the built-in set.
The Rubric dimensions section only appears when the PR risk assessment mode is not `off`.
##### Risk Floors
Deterministic rules that set a minimum risk level from a PR/MR's change metrics or from the findings its review produced. Each rule pairs a condition expression — metrics compared against thresholds, combinable with AND/OR/NOT — with a minimum level (`medium`, `high`, or `critical`). When a rule matches, the risk level is floored so that a lower level cannot be assigned; the strictest matching rule wins. Up to 20 rules per profile.
Available metrics:
* **Total LOC added** / **Total LOC removed** / **Total LOC changed** — whole-PR line counts, including files the review skips because of size or configuration.
* **Findings** — how many findings the review published.
* **Requirements with findings** — how many distinct requirements those findings were attributed to.
The two finding metrics can be narrowed to a single [finding type](#finding-types), so a rule can read "3 or more Security findings, at least `high`" or "10 or more Bug findings, at least `medium`". Leave the category as **Any category** to count them all together.
**Default:** no rules
The Risk floors section only appears when the PR risk assessment mode is not `off`. Floors only ever raise the assessed level — a rule can never lower one.
Line-count metrics cover the whole PR, but finding metrics count only what the review published. A file the review skipped, a finding type you hid, a low-quality comment, and a finding from an `audit`-mode requirement all contribute nothing to a finding rule.
##### Merge Gate
Zenable publishes a `Zenable Risk Assessment` status on each PR carrying its latest risk assessment — pending until the PR has been assessed, and carried forward to new commits on push. This can be used to define downstream policies, such as [risk-based reviews](/integrations/vcs-reviewers/risk-based-reviews). When enabled, Zenable will merge a PR only when the PR author applies the configured **Ready to merge label** (to indicate consent) and the configured risk threshold isn't exceeded. Adding the **Needs-review label** forces peer review at any risk level.
**Default:** disabled
Setup, branch protection, and the merge flow: [Risk-Based Reviews](/integrations/vcs-reviewers/risk-based-reviews).
The Merge gate section only appears when the PR risk assessment mode is not `off`. Review cadence is unchanged — a push simply invalidates the status until the next review (e.g. a `/zenable` comment).
#### Finding Types
Each review comment is classified into one of the following labels. All are shown by default — deselect a type to hide comments with that label.
* **Bug** — Incorrect behavior, logic errors, or broken functionality
* **Readability** — Hard-to-follow code structure, unclear naming, or poor formatting
* **Performance** — Inefficient algorithms, unnecessary allocations, or scalability concerns
* **Complexity** — Overly complicated logic that could be simplified
* **Security** — Vulnerabilities, unsafe patterns, or missing input validation
* **Inconsistency** — Contradicts existing patterns, conventions, or nearby code
* **Accessibility** — Missing or incorrect accessibility support (ARIA, keyboard nav, color contrast)
* **Mistake** — Typos, copy-paste errors, or accidental omissions
* **Other** — Issues that don't fit the above categories
**Default:** All types visible. Deselect a type to suppress comments with that label.
### Review Targeting
Decide how confident Zenable must be prior to publishing a finding. Every requirement in scope is still judged against every reviewed file.
* **Thorough** — include lower confidence findings. Costs more per file.
* **Balanced** — the default, calibrated against real review outcomes. Right for most teams.
* **High signal** — high confidence findings only. Costs less per file.
**Default:** `Balanced`.
### IDE/Agent Hook
Settings that govern how the Zenable CLI emits findings to coding agents (Claude Code, Cursor, OpenCode, etc.) when the hook fires after edits.
#### Triage Instructions
The preamble emitted as `...` ahead of findings the first time findings surface in an agent session. The agent uses this preamble to decide how to triage each finding (label categories, fix-versus-defer guidance, output format).
Customize the text per config profile when your team wants a different triage protocol — for example, a stricter "fix everything before continuing" stance, or a more permissive "label only, don't fix" workflow. Leave the field empty to fall back to the in-binary default that ships with the CLI.
The block is always emitted; setting an empty value falls back to the default rather than suppressing it. To change the wording for a specific repo, assign that repo to a config profile with the desired text.
## Default Configuration
### Preflight
* **enabled**: `true`
* **max\_changed\_lines**: `2500`
### PR Quality Filter
* **enabled**: `true`
* **quality\_threshold**: `0.5`
### Review Drafts
* **review\_drafts**: `true`
### PR/MR Description
* **mode**: `full`
* **edit\_trigger**: `always`
### PR/MR Risk Assessment
* **mode**: `comment_and_label`
### IDE/Agent Hook
* **triage\_instructions**: built-in default (the CLI ships a multi-line preamble that labels findings as `addressed`, `deferred`, `out-of-scope`, `rule-mismatch`, or `already-mitigated`).
### Files Excluded by Default
The following files are automatically excluded by default across all Zenable integrations:
```toml expandable theme={null}
conda-lock.yml
bun.lock
go.mod
requirements.txt
uv.lock
.terraform.lock.hcl
Gemfile.lock
package-lock.json
pnpm-lock.yaml
yarn.lock
composer.lock
poetry.lock
pdm.lock
Cargo.lock
go.sum
Package.resolved
Podfile.lock
mix.lock
*.ico
*.jpeg
*.jpg
*.png
*.svg
```
By default, no branches are skipped.
## Troubleshooting
If you're having issues with the GitHub or GitLab reviewers, try the following:
* Verify your configuration in **Company Settings → Configurations** is correct.
* The skip\_branches option uses python regex to match the branch names. Ensure your regex patterns are valid.
* If any of these solutions don't work, contact our support team at [support@zenable.io](mailto:support@zenable.io).
# GitHub
Source: https://docs.zenable.io/integrations/vcs-reviewers/github
Set up the Zenable GitHub Reviewer in your organization
## Installation
Install the Zenable GitHub Reviewer here: [GitHub Reviewer](https://zenable.io/github?utm_source=docs\&utm_medium=github-integration\&utm_content=install)
## How It Works
The Zenable GitHub Reviewer automatically reviews pull requests in your repository, providing valuable feedback on code quality, security, and best practices. It leverages any Policy as Code or context you've configured in your tenant on [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=github-integration\&utm_content=tenant-config), ensuring consistent enforcement across your entire development workflow.
Once installed, it will:
1. **Monitor PR events** - Responds to pull request opens, updates, and review requests
2. **Analyze code changes** - Reviews modified files against your custom policies and organizational context
3. **Provide inline feedback** - Adds comments directly on the code with specific suggestions
4. **Maintain standards** - Ensures consistent code quality across your team
New workspaces review only PRs from authors linked to a Zenable user; bots and outside contributors are skipped. To change which users get reviews, see [Review Scope](/integrations/vcs-reviewers/configuration#review-scope).
### Re-requesting a Review
You can trigger a new review at any time by commenting `/zenable` on your pull request. This is useful when:
* You've made changes and want fresh feedback
* You want to re-run the review after updating your policies
* The initial review was skipped due to rate limits or other conditions
Simply add a comment with `/zenable` anywhere in the PR, and Zenable will perform a complete review of the current state of the pull request.
### Repository Custom Properties
Zenable reads your organization's [repository custom properties](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization) — the key/value metadata your org defines centrally, like `team`, `tier`, or `compliance` — and keeps them in sync automatically on installation, when repository access or property values change, and from repository metadata included in pull request events. They power two features:
* **Metadata-based scopes** — requirements and context that apply only to repos with matching properties (see [Repository Metadata Conditions](/requirements-and-guardrails#repository-metadata-conditions))
* **Automatic configuration profile assignment** — profiles that attach themselves to matching repos (see [Automatic Profile Assignment](/integrations/vcs-reviewers/configuration#automatic-profile-assignment))
This uses the GitHub App's organization-level **Custom properties** (read-only) permission for bulk synchronization. The app also requests repository-level **Custom properties** (read and write) so property values can be managed at repository scope when the organization's property definition allows repository actors to edit them. Organizations that installed the app before either permission was added will be prompted by GitHub to approve the update; everything else keeps working in the meantime, and property syncing starts once the organization permission is granted.
### Unified Context Across All Integration Points
All Zenable integration points (GitHub, GitLab, MCP, API) share the same context and policies from your Zenable tenant. This provides continuous enforcement
throughout the entire SDLC - consistently reinforced and fully automated. Whether developers are using AI tools locally, committing code, or creating
pull requests, the same standards and policies apply everywhere.
## Next Steps
After installation, you can:
* [Configure the reviewer](/integrations/vcs-reviewers/configuration) to match your team's standards
* Set up [pre-commit hooks](/integrations/pre-commit/getting-started) for developer-side enforcement
* Install the [MCP server](/integrations/mcp/getting-started) for real-time IDE feedback
* Define [custom policies](/use-cases/policy-as-code) specific to your organization
* Review our [deployment guide](/deployment-adoption) for team adoption strategies
* Explore [supply chain security](/use-cases/supply-chain-security) to protect your dependencies
* Check our [Roadmap](https://zenable.io/feedback?utm_source=docs\&utm_medium=github-integration\&utm_content=roadmap) to see what's coming next
# GitLab
Source: https://docs.zenable.io/integrations/vcs-reviewers/gitlab
Set up the Zenable GitLab Reviewer for GitLab.com
**Using Self-managed GitLab?** See our [Self-managed GitLab guide](/integrations/vcs-reviewers/gitlab-on-prem) for self-hosted GitLab installations (version 17+).
## Installation
### Prerequisites
To use Zenable with GitLab, you'll need to create a Personal Access Token (PAT) or Group Access Token with the appropriate permissions.
#### Option 1: Personal Access Token (Recommended for individual users)
**Best Practice**: Create a dedicated service account for Zenable rather than using your personal account. The reviews will be easier to attribute to the bot
user and it provides better security, easier management, and clearer audit trails.
##### Creating a Service Account (Recommended)
Create a new GitLab user for Zenable:
* **Username**: `zenable-bot` or `zenable-reviewer`
* **Email**: Use a dedicated email (e.g., `zenable-bot@yourcompany.com`)
* **Profile picture**: Consider using zenable's logo ([here](https://www.zenable.app/zenable_dark.svg) or [here](https://www.zenable.app/zenable_light.svg)) as profile picture so its easier to understand that the reviews are coming from Zenable.
* **Access level**: Ensure this user has at least **Developer** access to the groups or projects where you want Zenable to review code
Log in as the service account and navigate to access tokens:
1. Click on your **avatar** in the top-right corner
2. Select **Edit Profile**
3. Click **Access Tokens** in the left sidebar
4. Click **[Add new token](https://gitlab.com/-/user_settings/personal_access_tokens)**
**Token name**: `zenable-integration` (or any descriptive name)
**Expiration date**: Set according to your security policy (recommended: Long enough so you don't have to rotate it often). Remember to update/rotate this token before it expires.
**Select scopes**: Enable the following permissions:
* ✅ `api` - Full API access (required for reading MRs, posting comments, and listing projects to manage webhooks)
* ✅ `read_user` - Read user information
1. Click **Create personal access token**
2. **Critical**: Copy the token immediately - it will only be displayed once
Keep your Personal Access Token secure. Anyone with this token can access your GitLab account with the permissions you've granted. Never commit tokens to
version control or share them in plain text.
#### Option 2: Group Access Token (GitLab Premium/Ultimate)
If you have GitLab Premium or Ultimate, you can use Group Access Tokens which automatically create a dedicated bot user.
1. Go to your GitLab group
2. Select **Settings** from the left sidebar
3. Select **Access Tokens** within the Settings section
1. Click **Create a Group Access Token**
2. Enter a descriptive name (e.g., `zenable-reviewer`)
3. Set an expiration date
4. Select the **`api`** scope
5. Ensure **Developer** access is provided
6. Click **Create group access token**
GitLab will automatically create a bot user (e.g., `group_123_bot_456...`) and display the token. Copy and store it securely immediately.
### Step 2: Configure Zenable
Go to [zenable.app/integrations](https://www.zenable.app/integrations?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=setup) and select the **GitLab** tab
1. Click **Connect GitLab**
2. Paste your Personal Access Token or Group Access Token in the **Access Token** field
3. Click **Add Server**
Zenable will automatically discover all accessible projects from your GitLab account.
After the installation is registered, your projects appear inline on the integrations page:
1. Toggle **MR Reviews** on for each project you want Zenable to review
2. Click **Save Changes** in the sticky bar at the bottom to apply your configuration
3. If you have multiple GitLab installations, each appears as an expandable accordion section identified by its GitLab URL
You can also use **Resync** to refresh the project list from GitLab, or **Delete** to remove an installation entirely.
Only enabled projects will receive automated merge request reviews from Zenable.
## How It Works
The Zenable GitLab Reviewer automatically reviews merge requests in your repository, providing valuable feedback on code quality, security, and best practices.
It leverages any Policy as Code or context you've configured in your tenant on [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=tenant-config), ensuring consistent enforcement across
your entire development workflow.
Once configured, it will:
1. **Monitor MR events** - Responds to merge request opens, updates, and review requests
2. **Analyze code changes** - Reviews modified files against your custom policies and organizational context
3. **Provide inline feedback** - Adds comments directly on the code with specific suggestions
4. **Maintain standards** - Ensures consistent code quality across your team
New workspaces review only MRs from authors linked to a Zenable user; bots and outside contributors are skipped. To change which users get reviews, see [Review Scope](/integrations/vcs-reviewers/configuration#review-scope).
### Re-requesting a Review
You can trigger a new review at any time by commenting `/zenable` on your merge request. This is useful when:
* You've made changes and want fresh feedback
* You want to re-run the review after updating your policies
* The initial review was skipped due to rate limits or other conditions
Simply add a comment with `/zenable` anywhere in the MR, and Zenable will perform a complete review of the current state of the merge request.
### Unified Context Across All Integration Points
All Zenable integration points (GitLab, GitHub, MCP, API) share the same context and policies from your Zenable tenant. This provides continuous enforcement
throughout the entire SDLC - consistently reinforced and fully automated. Whether developers are using AI tools locally, committing code, or creating merge
requests, the same standards and policies apply everywhere.
## Security Best Practices
**Always use a dedicated service account** instead of personal accounts:
* Create a separate GitLab user specifically for Zenable (e.g., `zenable-bot`)
* Use a dedicated email address for easy identification
* Provides clear audit trails and easier access management
* Makes it obvious in MR comments that it's an automated review
Regularly rotate your Personal Access Tokens:
* Set expiration dates on all tokens
* Create new tokens before old ones expire
* Update the token in Zenable settings promptly
* Revoke tokens that are no longer needed
* Document token renewal dates in your team calendar
Only grant the minimum required scopes:
* **Required**: `api` scope (provides all necessary access)
* **Required**: `read_user` scope (for user information)
* Ensure the service account has **Developer** access level
## Next Steps
After installation, you can:
* [Configure the reviewer](/integrations/vcs-reviewers/configuration) to match your team's standards
* Set up [pre-commit hooks](/integrations/pre-commit/getting-started) for developer-side enforcement
* Install the [MCP server](/integrations/mcp/getting-started) for real-time IDE feedback
* Define [custom policies](/use-cases/policy-as-code) specific to your organization
* Review our [deployment guide](/deployment-adoption) for team adoption strategies
* Explore [supply chain security](/use-cases/supply-chain-security) to protect your dependencies
* Check our [Roadmap](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=roadmap) to see what's coming next
## Troubleshooting
* Verify your PAT has the [correct scopes](#prerequisites)
* Check that the token hasn't expired — [create a new one](#prerequisites) if needed
* Ensure the repository is selected in Zenable settings
* Check GitLab webhook logs for errors
* Confirm the PAT has `api` and `read_user` scopes — see [Prerequisites](#prerequisites) for how to create one
* Verify the token owner has access to the repository
* Check if branch protection rules are blocking comments
* [Create a new PAT](#prerequisites) following the setup steps
* Update the token in Zenable settings
* Make sure you are entering the **base URL** of your GitLab instance (e.g. `https://gitlab.com`), not a project or group page URL
For additional support, please submit feedback at [zenable.io/feedback](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-integration\&utm_content=support).
# Self-managed GitLab
Source: https://docs.zenable.io/integrations/vcs-reviewers/gitlab-on-prem
Set up the Zenable GitLab Reviewer for self-hosted GitLab installations
**Using GitLab.com (Cloud)?** See our [GitLab guide](/integrations/vcs-reviewers/gitlab) for GitLab SaaS installations.
**Version Requirement:** Zenable supports GitLab 17.x and newer; please ensure your self-hosted GitLab instance meets this requirement.
## Network Access
If your self-managed GitLab instance is behind a firewall or restricts inbound traffic, allow the following so Zenable can reach your GitLab API:
* **Source IPs**: Zenable connects from a stable, published set of egress IPs. The current list is served as `A` records on `egress.www.zenable.app` — resolve that hostname (or [view it via mxtoolbox](https://mxtoolbox.com/SuperTool.aspx?action=a%3aegress.www.zenable.app\&run=toolpage)) and allowlist every address returned. The set may change as we scale, so re-resolve periodically rather than hardcoding individual IPs.
* **User-Agent**: All outbound requests from Zenable to your GitLab instance set a `User-Agent` header of the form `Zenable/GitLab ` (e.g. `Zenable/GitLab d08b553b6123`). If you front GitLab with a WAF or proxy, allow this User-Agent so requests aren't filtered.
## Installation
### Prerequisites
To use Zenable with GitLab, you'll need to create a Personal Access Token (PAT) or Group Access Token with the appropriate permissions.
#### Option 1: Personal Access Token (Recommended for individual users)
**Best Practice**: Create a dedicated service account for Zenable rather than using your personal account. The reviews will be easier to attribute to the bot
user and it provides better security, easier management, and clearer audit trails.
##### Creating a Service Account (Recommended)
Create a new GitLab user for Zenable:
* **Username**: `zenable-bot` or `zenable-reviewer`
* **Email**: Use a dedicated email (e.g., `zenable-bot@yourcompany.com`)
* **Profile picture**: Consider using zenable's logo ([here](https://www.zenable.app/zenable_dark.svg) or [here](https://www.zenable.app/zenable_light.svg)) as profile picture so its easier to understand that the reviews are coming from Zenable.
* **Access level**: Ensure this user has at least **Developer** access to the groups or projects where you want Zenable to review code
Log in as the service account and navigate to access tokens:
1. Click on your **avatar** in the top-right corner
2. Select **Edit Profile**
3. Click **Access Tokens** in the left sidebar
4. Click **Add new token**
**Token name**: `zenable-integration` (or any descriptive name)
**Expiration date**: Set according to your security policy (recommended: Long enough so you don't have to rotate it often). Remember to update/rotate this token before it expires.
**Select scopes**: Enable the following permissions:
* ✅ `api` - Full API access (required for reading MRs, posting comments, and listing projects to manage webhooks)
* ✅ `read_user` - Read user information
1. Click **Create personal access token**
2. **Critical**: Copy the token immediately - it will only be displayed once
Keep your Personal Access Token secure. Anyone with this token can access your GitLab account with the permissions you've granted. Never commit tokens to
version control or share them in plain text.
#### Option 2: Group Access Token (GitLab Premium/Ultimate)
If you have GitLab Premium or Ultimate, you can use Group Access Tokens which automatically create a dedicated bot user.
1. Go to your GitLab group
2. Select **Settings** from the left sidebar
3. Select **Access Tokens** within the Settings section
1. Click **Create a Group Access Token**
2. Enter a descriptive name (e.g., `zenable-reviewer`)
3. Set an expiration date
4. Select the **`api`** scope
5. Ensure **Developer** access is provided
6. Click **Create group access token**
GitLab will automatically create a bot user (e.g., `group_123_bot_456...`) and display the token. Copy and store it securely immediately.
### Step 2: Configure Zenable
Go to [zenable.app/integrations](https://www.zenable.app/integrations?utm_source=docs\&utm_medium=gitlab-onprem\&utm_content=setup) and select the **GitLab** tab
1. Click **Connect GitLab**
2. In the **GitLab Type** dropdown, select **Self-Managed GitLab**
3. Enter your self-hosted GitLab instance URL in the **GitLab URL** field (e.g., `https://gitlab.yourcompany.com`)
4. Paste your Personal Access Token or Group Access Token in the **Access Token** field
5. Click **Add Server**
Zenable will automatically discover all accessible projects from your GitLab account.
After the installation is registered, your projects appear inline on the integrations page:
1. Toggle **MR Reviews** on for each project you want Zenable to review
2. Click **Save Changes** in the sticky bar at the bottom to apply your configuration
3. If you have multiple GitLab installations, each appears as an expandable accordion section identified by its GitLab URL
You can also use **Resync** to refresh the project list from GitLab, or **Delete** to remove an installation entirely.
Only enabled projects will receive automated merge request reviews from Zenable.
## How It Works
The Zenable GitLab Reviewer automatically reviews merge requests in your repository, providing valuable feedback on code quality, security, and best practices.
It leverages any Policy as Code or context you've configured in your tenant on [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=gitlab-onprem\&utm_content=tenant-config), ensuring consistent enforcement across
your entire development workflow.
Once configured, it will:
1. **Monitor MR events** - Responds to merge request opens, updates, and review requests
2. **Analyze code changes** - Reviews modified files against your custom policies and organizational context
3. **Provide inline feedback** - Adds comments directly on the code with specific suggestions
4. **Maintain standards** - Ensures consistent code quality across your team
### Re-requesting a Review
You can trigger a new review at any time by commenting `/zenable` on your merge request. This is useful when:
* You've made changes and want fresh feedback
* You want to re-run the review after updating your policies
* The initial review was skipped due to rate limits or other conditions
Simply add a comment with `/zenable` anywhere in the MR, and Zenable will perform a complete review of the current state of the merge request.
### Unified Context Across All Integration Points
All Zenable integration points (GitLab, GitHub, MCP, API) share the same context and policies from your Zenable tenant. This provides continuous enforcement
throughout the entire SDLC - consistently reinforced and fully automated. Whether developers are using AI tools locally, committing code, or creating merge
requests, the same standards and policies apply everywhere.
## Security Best Practices
**Always use a dedicated service account** instead of personal accounts:
* Create a separate GitLab user specifically for Zenable (e.g., `zenable-bot`)
* Use a dedicated email address for easy identification
* Provides clear audit trails and easier access management
* Makes it obvious in MR comments that it's an automated review
Regularly rotate your Personal Access Tokens:
* Set expiration dates on all tokens
* Create new tokens before old ones expire
* Update the token in Zenable settings promptly
* Revoke tokens that are no longer needed
* Document token renewal dates in your team calendar
Only grant the minimum required scopes:
* **Required**: `api` scope (provides all necessary access)
* **Required**: `read_user` scope (for user information)
* Ensure the service account has **Developer** access level
## Next Steps
After installation, you can:
* [Configure the reviewer](/integrations/vcs-reviewers/configuration) to match your team's standards
* Set up [pre-commit hooks](/integrations/pre-commit/getting-started) for developer-side enforcement
* Install the [MCP server](/integrations/mcp/getting-started) for real-time IDE feedback
* Define [custom policies](/use-cases/policy-as-code) specific to your organization
* Review our [deployment guide](/deployment-adoption) for team adoption strategies
* Explore [supply chain security](/use-cases/supply-chain-security) to protect your dependencies
* Check our [Roadmap](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-onprem\&utm_content=roadmap) to see what's coming next
## Troubleshooting
* Verify your PAT has the [correct scopes](#prerequisites)
* Check that the token hasn't expired — [create a new one](#prerequisites) if needed
* Ensure the repository is selected in Zenable settings
* Verify your self-hosted GitLab instance is accessible from the internet — see [Network Access](#network-access)
* Check GitLab webhook logs for errors
* Confirm the PAT has `api` and `read_user` scopes — see [Prerequisites](#prerequisites) for how to create one
* Verify the token owner has access to the repository
* Check if branch protection rules are blocking comments
* [Create a new PAT](#prerequisites) following the setup steps
* Update the token in Zenable settings
* Verify your GitLab instance is running **version 17.0 or newer**
* Check GitLab version: Navigate to **Admin Area** > **Overview** or run `gitlab-rake gitlab:env:info`
* Make sure you are entering the **base URL** of your GitLab instance (e.g. `https://gitlab.example.com`), not a project or group page URL
* Your GitLab URL must use **HTTPS** — HTTP is not supported for self-managed instances
* Self-signed TLS certificates are not supported; your instance must use a certificate from a trusted CA — see [Network Access](#network-access) for connectivity requirements
For additional support, please submit feedback at [zenable.io/feedback](https://zenable.io/feedback?utm_source=docs\&utm_medium=gitlab-onprem\&utm_content=support).
# Risk-Based Reviews
Source: https://docs.zenable.io/integrations/vcs-reviewers/risk-based-reviews
Let authors merge low-risk, Zenable-reviewed PRs without waiting on peer review
Many teams have decided that low-risk changes reviewed by Zenable's coding verifiers are able to merge to main without human review. Stop queueing low-risk, routine changes behind human review, significantly reducing lead time for changes and end-to-end cycle time. To implement this for yourself, enable the [PR risk assessment](/integrations/vcs-reviewers/configuration#prmr-risk-assessment), publish it as a required check, and update your rulesets — then you're all set.
GitHub only today. On GitHub the checks are native check runs (rich output, re-runnable from the PR's checks tab); on GitLab they publish as commit statuses, and merge execution is GitHub-specific.
## Enable It
1. Go to [Settings → Configuration](https://www.zenable.app/settings?utm_source=docs\&utm_medium=risk-based-reviews\&utm_content=settings\&tab=configuration) and pick the profile your repos use.
2. Under **PR/MR risk assessment** (mode must not be Off), switch on **Merge gate**.
3. Set your knobs:
* **Auto-merge risk threshold** — highest assessed risk an author may merge without review (default `low`)
* **Ready to merge label** — the label an author applies to say "merge this" (default `Ready to merge`)
* **Needs-review label** — always forces peer review, at any risk level (default `zenable/needs-review`)
To guarantee certain changes always get peer review regardless of the AI assessment, add [risk floors](/integrations/vcs-reviewers/configuration#risk-floors) — deterministic rules like "more than 1,000 changed lines is at least medium risk" that ensure a minimum risk.
Once enabled, Zenable posts a `Zenable Risk Assessment` check on every PR: **pending** while reviewing, **passing** with the assessed level once done. The check's output explains that level — a table scoring every [rubric dimension](/integrations/vcs-reviewers/configuration#prmr-risk-assessment) 0–10, the weighted composite they produce, and the risk floor when one raised the result. The assessment rides the PR — a push carries the latest result forward to the new commit, so nothing goes red or pending mid-iteration. Review timing is unchanged and configured in one place — see [Reviewer Configuration](/integrations/vcs-reviewers/configuration#review-check-on-commits) for when reviews run and how to request one. Before moving on, open a small test PR and confirm the configuration works as expected: the check goes **pending**, then **passes** with an assessed level, the risk label lands on the PR, and the assessment summary appears in the check's output.
## Wire It Into Branch Protection
We recommend creating three rulesets on your default branch (**Repo → Settings → Rules → Rulesets**): your CI baseline, an AI review ruleset, and a human review ruleset:
Your existing required checks, such as requiring linear history, and a **Require a pull request** rule with **0 approvals**.
One required status check: `Zenable Risk Assessment`, with the **Zenable App selected as the source**. Consider adding org admins as bypass actors (*For pull requests only*) as a break-glass if Zenable is ever unavailable.
Your human review requirements, when they apply (for instance, approval count and code owners). Add the **Zenable App** as a bypass actor, *For pull requests only*. This is the only ruleset Zenable can bypass, and only for acceptable levels of risk after the author requests to merge (by attaching the appropriate label) so they maintain full control over timing.
## Merging a Low-Risk PR
As the PR author, once the check shows your PR at or below the threshold, and if you'd like to merge your PR:
* **Enable auto-merge** on the PR (to define the merge method and commit message you want Zenable to use), or
* **Apply the Ready to merge label** yourself. Importantly, the label must be applied by the PR author for it to be considered.
Zenable re-verifies that the assessment is within your configured risk threshold and the needs-review label is absent, then merges. CI and the risk assessment still apply in full; only peer review is waived. Anything above the threshold goes through your normal review flow untouched.
To force review on a specific PR regardless of risk, apply the needs-review label.
## Review Check (no gating)
Want visibility without any merge policy? Enable **Review check on commits** under **PR Reviews** in the same configuration profile. Zenable adds a `Zenable Review` check on all PRs that are enabled for PR reviews, set as **passing** when the review has completed (naming the assessed risk level) and **skipped** for each commit that hasn't been reviewed. Because skipped counts as passing on GitHub, it informs without gating, and it works alongside or entirely independent of risk-based merging.
# Zenable CLI Reference
Source: https://docs.zenable.io/integrations/zenable/commands
Complete reference for all zenable CLI commands and options
## Quick Installation
```bash theme={null}
curl -fsSL https://cli.zenable.app/install.sh | bash
```
```powershell theme={null}
powershell -ExecutionPolicy Bypass -Command "irm https://cli.zenable.app/install.ps1 | iex"
```
Sometimes virus scanners [flag Go binaries as suspicious](https://go.dev/doc/faq#virus).
All Zenable binaries are signed with a platform-appropriate approach, and
every release ships with SHA-256 checksums that are always verified at
install time. On Windows, the binary is Authenticode signed (Azure Trusted
Signing) and that signature is always verified during installation. On
Linux and macOS, the binary is [cosign](https://www.sigstore.dev/) signed
and verified when cosign or Docker is available. If your scanner flags the
binary, please report it to your antivirus vendor.
For more installation options, see the [Getting Started](/integrations/mcp/getting-started?utm_source=docs\&utm_medium=web) guide.
## Overview
Zenable CLI - conformance checking, IDE management, and hook handling for agentic IDEs.
The `zenable` CLI is the native Go binary for conformance checking, IDE management, and hook handling.
## Global Options
These options are available for all commands:
| Option | Description |
| - | - |
| `-v`, `--verbose` | Enable verbose output (repeatable: `-v`, `-vv`) |
| `-h`, `--help` | Show help message |
## Commands
### `install`
Install the Zenable integrations.
```bash theme={null}
zenable install [OPTIONS] [COMMAND] [ARGS]...
```
**Note**: You can use unified commands like `install cursor` or `install claude-code`, or use subcommands like `install mcp cursor` and `install hook claude-code`. The unified commands are simpler and install all features.
#### Options
| Option | Description |
| - | - |
| `-d`, `--dry-run` | Preview what would be done without actually performing the installation |
| `-p`, `--project` | Install in the project directory instead of globally |
| `--include TEXT` | Include only directories matching these glob patterns (e.g., `'**/microservice-*'`) |
| `--exclude TEXT` | Exclude directories matching these glob patterns |
| `--all` | Install for all supported IDEs, even if not currently installed |
| `-h`, `--help` | Show help message |
By default, `zenable install` installs globally so the integration is available across all your projects.
**Want project-level installation?** Run `zenable install --project` from inside a git repository to install only for that project. When using `--project` outside a git repository, the installer will present an interactive TUI to select which repositories to install into.
#### Subcommands
##### `install mcp`
Install Zenable MCP server configuration.
**Uses OAuth for secure authentication.**
```bash theme={null}
zenable install mcp [OPTIONS] COMMAND [ARGS]...
```
Additional options:
| Option | Description |
| - | - |
| `--overwrite` | Overwrite existing Zenable configuration if it exists |
| `--no-instructions` | Don't show post-installation instructions |
Supported IDE commands:
* `all` - Install MCP for all detected IDEs (default)
* `amp` - Install MCP for [Amp](/integrations/mcp/ide/amp)
* `antigravity` - Install MCP for [Antigravity](/integrations/mcp/ide/antigravity)
* `antigravity-cli` - Install MCP for [Antigravity CLI](/integrations/mcp/ide/antigravity-cli) (successor to Gemini CLI)
* `auggie` (alias: `augment`) - Install MCP for [Auggie](/integrations/mcp/ide/auggie)
* `claude-code` (alias: `claude`) - Install MCP for [Claude Code](/integrations/mcp/ide/claude-code)
* `codex` - Install MCP for [Codex](/integrations/mcp/ide/codex)
* `copilot-cli` - Install MCP for [GitHub Copilot CLI](/integrations/mcp/ide/copilot)
* `cursor` - Install MCP for [Cursor](/integrations/mcp/ide/cursor) IDE and cursor-agent CLI
* `devin-desktop` (alias: `devin`) - Install MCP for [Devin Desktop](/integrations/mcp/ide/devin-desktop)
* `kiro` - Install MCP for [Kiro](/integrations/mcp/ide/kiro)
* `vscode` - Install MCP for [Visual Studio Code](/integrations/mcp/ide/vscode)
##### `install hook`
Install hooks for various tools.
```bash theme={null}
zenable install hook [OPTIONS] COMMAND [ARGS]...
```
Supported hook commands:
* `all` - Install hooks for all supported tools
* `claude-code` (alias: `claude`) - Install Claude Code hooks
* `cursor` - Install Cursor hooks
* `devin-desktop` (alias: `devin`) - Install Devin Desktop (Cascade) hooks
###### Options
| Option | Description |
| - | - |
| `--dry-run` | Preview what would be done without actually performing the installation |
| `--include TEXT` | Include only directories matching these glob patterns (e.g., `'**/microservice-*'`) |
| `--exclude TEXT` | Exclude directories matching these glob patterns |
| `-h`, `--help` | Show help message |
#### Examples
```bash theme={null}
# Install globally for all detected IDEs (recommended)
zenable install
# Install for a specific IDE using unified command (recommended)
zenable install cursor
zenable install claude-code
# Install in the current project only
zenable install --project
# Preview what would be done without installing
zenable install --dry-run
# Advanced: Install only MCP (without hooks) for all detected IDEs
zenable install mcp
# Advanced: Install only MCP for a specific IDE
zenable install mcp cursor
# Advanced: Install only hooks
zenable install hook
zenable install hook claude-code
zenable install hook cursor
```
### `uninstall`
Remove Zenable integrations from your system.
```bash theme={null}
zenable uninstall [OPTIONS]
```
Launches an interactive TUI to select which integrations to remove.
#### Options
| Option | Description |
| - | - |
| `-d`, `--dry-run` | Preview what would be done without actually performing the uninstall |
| `-p`, `--project` | Uninstall from the project directory instead of globally |
| `--all` | Uninstall from all IDEs without interactive selection |
| `-h`, `--help` | Show help message |
### `check`
Check the provided files against your conformance tests.
```bash theme={null}
zenable check [OPTIONS] [PATTERNS]...
```
Automatically detects files from IDE context when no patterns are provided.
Supports glob patterns like `**/*.py` to check all Python files recursively.
Accepts piped input via stdin from `git status --short` or plain file lists.
Files are processed in batches for optimal performance. Standard files (up to
30,000 characters each) are grouped into batches; larger "jumbo" files are
reviewed one per request. Files above the jumbo ceiling (300,000 characters)
are skipped and listed in the review summary.
#### Arguments
* `PATTERNS`: Glob patterns for files to check (e.g., `'**/*.py'`, `'src/**/*.js'`)
* If no patterns are provided, auto-detects the last edited file, subject to filtering. Use `--verbose` for filtering details
#### Stdin
When input is piped to `zenable check`, it reads file paths from stdin. This supports:
* **`git status --short`** output — status prefixes are automatically stripped, deleted files are skipped, and renames use the new path
* **Plain file lists** — one file path per line
#### Path matching and requirement scopes
Path patterns are relative to the git repo root; outside a git repo they
are compared to the absolute path of the file (and a warning is printed).
See [Scoping requirements](/requirements-and-guardrails#scoping-requirements).
#### Options
| Option | Description |
| - | - |
| `--exclude TEXT` | Patterns to exclude from checking |
| `--base-path DIRECTORY` | Base directory for pattern matching (defaults to current directory) |
| `--branch` | Check all files changed on the current branch compared to the base branch |
| `--base-branch TEXT` | Base branch to compare against when using `--branch` (default: `$ZENABLE_CHECK_BASE_BRANCH` or `main`) |
| `--dry-run` | Show which files would be sent without actually checking them |
| `--format TEXT` | Output format(s): `text`, `json`, `sarif`, or `html`. Supports multiple formats and file paths (e.g. `text,sarif=results.sarif`). Default: `text` |
| `--skip-ai-review` | Skip AI review (overrides config and env var) |
| `--skip-semgrep` | Skip semgrep guardrails (overrides config and env var) |
| `-h`, `--help` | Show help message |
#### Configuration
The `check` command supports configuration via environment variables:
| Environment Variable | Description | Default |
| - | - | - |
| `ZENABLE_CHECK_BASE_BRANCH` | Default base branch to compare against when using `--branch` | `main` |
##### Example
```bash theme={null}
# Set default base branch to develop
export ZENABLE_CHECK_BASE_BRANCH=develop
# Now --branch uses develop instead of main
zenable check --branch
# CLI option still overrides env var
zenable check --branch --base-branch feature/base
```
#### Examples
```bash expandable theme={null}
# Check a single file
zenable check example.py
# Check everything under the current directory (full repo sweep when run
# from the repository root)
zenable check .
# Check all Python files recursively
zenable check '**/*.py'
# Check multiple patterns
zenable check 'src/**/*.js' 'tests/**/*.js'
# Pipe git status to check modified/untracked files
git status --short | zenable check
# Pipe a file list from any command
find src -name '*.py' | zenable check
# Exclude test files from checking
zenable check '**/*.py' --exclude '**/test_*.py'
# Specify base directory for pattern matching
zenable check '*.py' --base-path ./src
# Check all files changed on current branch compared to main
zenable check --branch
# Check all files changed on current branch compared to develop
zenable check --branch --base-branch develop
# Check only Python src files changed on current branch
zenable check --branch '**/*.py' --exclude '**/test_*.py'
# Dry run to see which files would be checked
zenable check '**/*.py' --dry-run
# Output results in SARIF format to a file (e.g. for CI integration)
zenable check '**/*.py' --format sarif=results.sarif
# Output results in JSON format to a file
zenable check '**/*.py' --format json=results.json
# Output text to terminal and write SARIF + JSON to files
zenable check '**/*.py' --format text,sarif=results.sarif,json=results.json
# Output HTML report to a file
zenable check '**/*.py' --format html=report.html
# Output multiple formats to stdout
zenable check '**/*.py' --format sarif,json
# Skip AI review and only run semgrep guardrails
zenable check '**/*.py' --skip-ai-review
```
### `hook`
Handle calls from the hooks of Agentic IDEs.
```bash theme={null}
zenable hook [OPTIONS]
```
This command is specifically designed for IDE integrations like Claude Code and Cursor.
It reads hook input from stdin, processes the files, and returns appropriate
exit codes and formatted responses for the IDE to handle.
To manually run a scan, use the `check` command instead.
#### Options
| Option | Description |
| - | - |
| `-h`, `--help` | Show help message |
**Reverted files are not reviewed.** When an agent modifies a file and then reverts it back to match the base branch (e.g., via `git checkout`), the hook will report "No files to process" because there is no net change compared to the base branch. This is expected behavior — Zenable reviews the *diff*, not individual edits, so if the final state matches what's already on the base branch, there's nothing new to review.
### `triage`
Fetch and address unresolved review comments on a pull request or merge request.
```bash theme={null}
zenable triage [OPTIONS]
```
Auto-detects the PR (GitHub) or MR (GitLab) for the current branch and fetches every commentable surface — line-level review threads, PR-level issue comments, and submitted-review summary bodies — in a single XML payload aimed at AI coding agents. By default only comments from the Zenable AI guardrails bot are returned; flags loosen that filter.
The default output embeds an `` block telling the agent how to process each thread (commit per thread, push, then reply). Use `--reply` to post a response to a single thread, or `--report-only` to emit a read-only research-report prompt that produces no commits, pushes, or replies.
#### Modes
| Mode | Flag | What it does |
| - | - | - |
| List (default) | *none* | Print threads + an `` block guiding the agent to fix, commit, push, and reply. |
| Reply | `--reply` | Post a single reply to a thread, either referencing a commit (`--commit`) or with a custom body (`--comment`). |
| Report-only | `--report-only` | Emit a prompt that has the agent research each comment and print a structured markdown report to stdout — no commits, no pushes, no replies. |
#### Options
| Option | Description |
| - | - |
| `--pr INTEGER` | GitHub PR number (auto-detected from current branch if omitted). Mutually exclusive with `--mr`. |
| `--mr INTEGER` | GitLab MR number (auto-detected from current branch if omitted). Mutually exclusive with `--pr`. |
| `--all-bots` | Include comments from all bots, not just the Zenable AI guardrails bot. |
| `--all-authors` | Include comments from all authors (humans and bots). |
| `--include-resolved` | Include resolved review threads. Only applies to line-level threads; issue comments and review summaries have no resolve concept. |
| `--format TEXT` | Output format: `xml` (default), `json`, or `text`. |
| `--push-strategy TEXT` | How commits and replies are sequenced in default-mode instructions: `batch` (default — commit per thread, push once, then reply) or `each` (commit, push, reply per thread). Ignored when `--report-only` is set. |
| `--reply` | Reply to a single thread. Requires `--thread-id` and one of `--commit`/`--comment`. Mutually exclusive with `--report-only`. |
| `--thread-id TEXT` | Thread ID to reply to (used with `--reply`). |
| `--commit TEXT` | Commit hash that addresses the thread (used with `--reply`). Mutually exclusive with `--comment`. |
| `--comment TEXT` | Custom reply body (used with `--reply`). Mutually exclusive with `--commit`. |
| `--report-only` | Emit a read-only research-report prompt; no commits, pushes, or replies. Mutually exclusive with `--reply`. |
| `-h`, `--help` | Show help message. |
#### Examples
```bash expandable theme={null}
# List unresolved bot review comments (auto-detect PR/MR)
zenable triage
# List comments for a specific GitHub PR
zenable triage --pr 123
# List comments for a specific GitLab MR
zenable triage --mr 456
# Include comments from all authors, not just the bot
zenable triage --all-authors
# Include resolved threads as well
zenable triage --include-resolved
# Switch to per-thread commit + push + reply cycles
zenable triage --push-strategy each
# Reply to a thread by referencing a commit
zenable triage --reply --thread-id PRRT_abc123 --commit abc123f
# Reply to a thread with a custom comment
zenable triage --reply --thread-id PRRT_abc123 --comment "Intentional, see docs"
# Emit a read-only research-report prompt — no commits, no replies
zenable triage --report-only
# Same, but as JSON for downstream tooling
zenable triage --report-only --format json
```
**Resolve state only applies to line-level review comments.** Issue comments (PR-level conversation) and review summaries (the body of a submitted review) have no resolve/unresolve concept, so `--include-resolved` is a no-op for them.
### `finding feedback`
Record an agent's triage verdict on a conformance finding emitted by the IDE hook. Agents call this automatically during the triage pass; you rarely need it by hand.
```bash theme={null}
zenable finding feedback [OPTIONS]
```
#### Options
| Option | Description |
| - | - |
| `--finding TEXT` | Opaque finding id from the hook's `` block (single form) |
| `--findings TEXT` | Comma-separated finding ids — apply one verdict/reason/context/mitigation across the whole set (mutually exclusive with `--finding` and `--batch`) |
| `--verdict TEXT` | Required: `applied` \| `deferred` \| `declined` \| `needs_human` |
| `--reason TEXT` | Required when `--verdict` ≠ `applied`: `out_of_scope` \| `rule_too_broad` \| `rule_too_specific` \| `mitigated_same_file` \| `mitigated_cross_file` \| `intent_mismatch` \| `wrong_code_shape` \| `conflicting_requirement` \| `other` |
| `--context TEXT` | One-line why (≤500 chars); required when `--verdict` ≠ `applied`, and optionally on `applied` as well |
| `--mitigation TEXT` | `path:line[-line]` pointing to the mitigation; required when `--reason` starts with `mitigated_` |
| `--conflicts-with TEXT` | For `--reason=conflicting_requirement`: the other side of the conflict — another finding id from this session (`f_xxxxxxxx`) or a requirement family id (UUIDv7) |
| `--batch` | Read a JSON array of `{finding, verdict, reason?, context?, mitigation?, conflicts_with?}` objects from stdin |
#### Examples
```bash theme={null}
# Single finding — applied, with a one-line why (optional but encouraged)
zenable finding feedback --finding=f_a3k9 --verdict=applied \
--context="the handler queried findings with no tenant filter"
# Single finding — declined with mitigation pointer
zenable finding feedback --finding=f_b2m1 --verdict=declined \
--reason=mitigated_cross_file \
--context="input validated by handlers/auth.go" \
--mitigation=handlers/auth.go:88
# Bulk — same verdict across several findings (e.g. a rebase collateral wave)
zenable finding feedback --findings=f_a3k9,f_b2m1,f_c4p7 \
--verdict=declined --reason=out_of_scope \
--context="collateral from main-merge; not touched on this branch"
# Conflicting requirements — one rule demands what another forbids
zenable finding feedback --finding=f_d8q2 --verdict=needs_human \
--reason=conflicting_requirement --conflicts-with=f_e5r3 \
--context="the retry rule wants a loop here; the no-retry-on-writes rule flags the same block"
# Batch — per-finding verdicts read from stdin
zenable finding feedback --batch < payload.json
```
### `self feedback`
Send free-form feedback about Zenable to the Zenable team. Requires authentication.
```bash theme={null}
zenable self feedback --message TEXT [--type TYPE]
```
#### Options
| Option | Description |
| - | - |
| `--message TEXT` | Feedback body (required, max 2000 chars) |
| `--type TEXT` | Optional bucket: `bug` \| `feature_request` \| `question` \| `praise` \| `other` |
#### Examples
```bash theme={null}
zenable self feedback --message "love the new triage flow" --type=praise
zenable self feedback --message "install script left dotfiles in \$HOME" --type=bug
zenable self feedback --message "would love a --json flag on check" --type=feature_request
```
### `report`
Record something the agent observed about its own working conditions while
coding — the session and the harness around it.
This is about the **agent's working conditions**, not about Zenable.
Feedback on a specific finding goes to [`finding feedback`](#finding-feedback);
feedback about Zenable itself goes to [`self feedback`](#self-feedback).
`report` is a parent verb with no options of its own. Each subcommand names one
category and supplies it, so the verb the agent types and the row it files can
never disagree:
```bash theme={null}
zenable report friction --message TEXT # something that exists fought you
zenable report gap --message TEXT # something you needed did not exist
zenable report conflict --message TEXT # two sources told you different things
zenable report debt --message TEXT # you knowingly left something worse
zenable report win --message TEXT # something worked notably better
```
#### Options
Every subcommand takes the same one flag.
| Option | Description |
| - | - |
| `--message TEXT` | The one specific thing observed (required, max 1024 chars) |
The agent-session id and IDE name are resolved automatically from the IDE hook,
so there are no `--session` or `--ide` flags; running outside a hook session is
fine and the report is still recorded, with those fields left empty. If nobody
is signed in, the report is logged locally and the command still exits 0 — an
agent-invoked command that fails is itself friction.
One observation per invocation, and the same one should not be reported twice
in a session.
#### Choosing a category
Each category answers a different question, and the boundaries between the
adjacent ones matter:
| Category | The test |
| - | - |
| `friction` | Something that exists fought you and cost time or steps. |
| `gap` | Something you needed did not exist at all. |
| `conflict` | Two sources of truth disagreed — name both sides. |
| `debt` | You knowingly left something worse than it should be, and why. |
| `win` | Something worked notably better than expected. |
A painful tool is `friction`; a missing one is `gap`. Two tools that contradict
each other is `conflict`.
#### Examples
```bash theme={null}
zenable report friction --message "had to re-read the same 3 files after every edit because no index of the handler wiring exists"
zenable report gap --message "no fixture builds a tenant with two linked identities, so every test in this file hand-rolls one"
zenable report conflict --message "AGENTS.md says never run formatters manually, but the commit hook rejects unformatted code, so landing a change means violating one of the two"
zenable report debt --message "left the retry count hardcoded at 3 because the config plumbing spans two services and was out of scope"
zenable report win --message "the migration policy test failed with the exact baseline number, so the fix was one edit and no guessing"
```
See the [agent integration guide](/integrations/zenable/commands) for how these
surfaces fit together.
### `self update`
Update the CLI to the latest release.
```bash theme={null}
zenable self update
```
Binary mode and ownership are preserved on update.
### `login`
Authenticate with Zenable via OAuth.
```bash theme={null}
zenable login
```
Opens a browser to complete the OAuth authentication flow. Credentials are cached locally for future commands. If already authenticated, skips re-authentication.
A sign-in lasts up to a week. The CLI renews its short-lived access token silently in the background, so you are only asked to sign in again once the week is up. `zenable doctor` and `zenable auth whoami` show when that is due.
### `logout`
Clear local OAuth credentials and revoke the session.
```bash theme={null}
zenable logout [OPTIONS]
```
Revokes the stored refresh token before clearing local credentials, so the session cannot be resumed from a copy of the credential cache. If the revocation cannot reach Auth0, local credentials are still cleared and a warning explains what was not revoked.
#### Options
| Option | Description |
| - | - |
| `--all` | Also open Auth0 logout in browser to end remote session |
### `auth can-i`
Check whether the authenticated user has a specific permission — or whether an MCP tool would be allowed to run. Prints `yes` or `no` and sets a matching exit code, so it's scriptable.
```bash theme={null}
# Check an RBAC permission (resource:verb or verb resource)
zenable auth can-i requirements:write
zenable auth can-i write requirements
# Check whether an MCP tool would be permitted to run
zenable auth can-i get_findings
# List every RBAC permission and MCP tool with its grant status
zenable auth can-i --list
```
Every Zenable RBAC permission and every MCP tool is covered. A tool is `yes` only when all of its gates pass (e.g. `update_marketplace_requirement` needs both `requirements:write` and `marketplace:publish`); otherwise it's `no`, and the per-gate breakdown on stderr names the gate that blocked it.
#### Options
| Option | Description |
| - | - |
| `--list` | List every RBAC permission and MCP tool with its grant status |
#### Exit codes
| Code | Meaning |
| - | - |
| `0` | Permitted |
| `1` | Denied |
### `sync`
Sync guardrails from Zenable to local disk.
```bash theme={null}
zenable sync
```
Downloads and caches semgrep guardrails locally for faster conformance checks. Uses ETag-based caching to avoid re-downloading unchanged guardrails. Requires authentication.
### `logs`
View zenable logs.
```bash theme={null}
zenable logs [OPTIONS]
```
#### Options
| Option | Description |
| - | - |
| `-f`, `--follow` | Follow log output (like `tail -f`) |
| `-r`, `--raw` | Show raw log entries instead of just messages |
| `-n`, `--lines INTEGER` | Number of lines to show (from end of file, default: 50) |
| `--clear` | Clear the log file (cannot be used with other options) |
| `-h`, `--help` | Show help message |
#### Examples
```bash theme={null}
# View recent logs
zenable logs
# Follow logs in real-time
zenable logs --follow
# Show last 50 lines
zenable logs -n 50
# Clear logs
zenable logs --clear
```
### `doctor`
Diagnose and troubleshoot installation and client issues.
```bash theme={null}
zenable doctor
```
Displays diagnostic information including OS details, terminal environment, Zenable environment variables (sensitive values redacted), dependency status, authentication state, custom guardrail validation status, and recent log entries.
The Custom Guardrails section reports each configured custom guardrail file by absolute path with one of the following statuses:
* `✓` — passed both upstream syntax and Zenable schema checks
* `✗` — failed Zenable schema validation
* `?` — partially or not yet validated; run `zenable guardrail validate ` for more details
### `guardrail`
Inspect and validate custom guardrail rules. The first positional argument selects the engine (`opengrep` or `semgrep`) — the server never infers it from the rule body. Subsequent arguments are file paths or glob patterns.
```bash theme={null}
zenable guardrail [SUBCOMMAND]
```
#### `guardrail validate`
Validate one or more custom guardrail rule files. Runs the engine's native `validate` command (catches YAML / pattern syntax errors) and the Zenable schema check (catches the field-level rules that protect the findings API). Validation results are cached locally by SHA-256 of the rule body, so re-running is free for unchanged files.
```bash theme={null}
zenable guardrail validate ...
```
##### Arguments
* `` — required; one of `opengrep` or `semgrep`. Explicit by design; the server never infers it from the rule body.
* `...` — one or more file paths or glob patterns. Globs expand relative to the current working directory. Excludes and config-driven skip-filenames do NOT apply: this command validates exactly what you point it at.
##### Options
* `--format ` — `text` (default) or `json`
##### Examples
```bash theme={null}
# Validate one file
zenable guardrail validate opengrep ~/.zenable/custom_guardrails/semgrep/custom-no-eval.yaml
# Validate every YAML rule in a directory
zenable guardrail validate semgrep '~/.zenable/custom_guardrails/semgrep/*.yaml'
# Machine-readable output for CI
zenable guardrail validate opengrep '**/*.yaml' --format json | jq
```
##### Exit Codes
* `0` — all files passed (or were partial-pass)
* `1` — at least one file failed validation
* `2` — bad arguments (unknown engine, no files matched)
### `version`
Show the zenable version.
```bash theme={null}
zenable version
```
Will also notify you if an update is available.
## Configuration Files
### MCP Server Configuration
The tool creates MCP server configuration in IDE-specific locations, appropriate for that individual IDE. For instance:
```json theme={null}
{
"mcpServers": {
"zenable": {
"type": "http",
"url": "https://mcp.zenable.app/"
}
}
}
```
### Hook Configuration (Claude Code)
Hooks are configured in Claude Code settings (`.claude/settings.json`):
```json expandable theme={null}
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit|MultiEdit",
"hooks": [
{
"type": "command",
"command": "zenable hook"
}
]
}
]
}
}
```
### Hook Configuration (Cursor)
Hooks are configured in Cursor hooks file (`.cursor/hooks.json`):
```json expandable theme={null}
{
"version": 1,
"hooks": {
"afterFileEdit": [
{
"command": "zenable hook"
}
]
}
}
```
## Exit Codes
| Code | Meaning |
| - | - |
| 0 | Success |
| 1 | General error |
| 2 | Conformance issues found |
| 3 | Handler conflict |
| 4 | No hook input |
| 12 | No files specified |
| 13 | No files found |
| 14 | File read error |
| 15 | Invalid parameters |
| 16 | File write error |
| 20 | API error |
| 21 | Authentication error |
| 22 | Sync error |
| 23 | Access blocked (no Zenable seat available) |
| 51 | Installation error |
| 52 | Partial success |
| 130 | User interrupt |
## File Patterns
### Glob Pattern Examples
```bash expandable theme={null}
# All Python files recursively
'**/*.py'
# Multiple extensions
'**/*.{js,ts,jsx,tsx}'
# Specific directory
'src/**/*.py'
# All files in current directory
'*'
# All files recursively
'**/*'
# Specific depth
'*/*.py' # One level deep
'*/*/*.py' # Two levels deep
```
### Common Exclusions
```bash expandable theme={null}
# Python
--exclude '**/{__pycache__,venv,.venv,migrations}/**'
# JavaScript/Node
--exclude '**/{node_modules,dist,build,.next}/**'
# General
--exclude '.git/**'
--exclude '**/*.min.js'
--exclude '**/*.map'
--exclude '**/vendor/**'
```
## Troubleshooting
### Debug Mode
Enable debug output for troubleshooting:
```bash theme={null}
# Maximum verbosity
zenable -vv install
# Run a check with verbose output
zenable -v check '**/*.py'
# View debug logs
zenable logs --lines 100
# Run diagnostics
zenable doctor
```
### Dry Run Mode
Preview changes without applying:
```bash theme={null}
# Preview installation
zenable install --dry-run
# Preview with specific IDE
zenable install mcp cursor --dry-run
```
## See Also
* [Getting Started](/integrations/mcp/getting-started?utm_source=docs\&utm_medium=web)
* [Troubleshooting](/integrations/mcp/troubleshooting?utm_source=docs\&utm_medium=web)
* [Use Cases](/use-cases/preventing-ai-mistakes?utm_source=docs\&utm_medium=web)
# Management Console
Source: https://docs.zenable.io/management-console
Configure custom quality guardrails and company requirements
## Overview
The Zenable management console at [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=web\&utm_content=management-console) is where you configure custom requirements that automatically enforce across your organization. Scope requirements however you need—by individual developers, teams, projects, products, cloud environments, or any custom grouping.
## Accessing the Console
### Supported Identity Providers
The Zenable management console supports Single Sign-On (SSO) through the following identity providers:
* **Google** - Sign in with your Google account
* **Microsoft Entra ID** (formerly Azure Active Directory) - Enterprise SSO for organizations using Microsoft identity services
* **Okta** - Enterprise SSO for organizations using Okta as their identity provider
* **Any OIDC-compliant IdP** - Keycloak, PingFederate, Auth0, or any provider that supports OpenID Connect
## Microsoft Entra ID Onboarding
Organizations using Microsoft Entra ID can enable SSO for their team members through our verified application.
### Setup Process
An administrator from your organization must install our [Verified Application](https://login.microsoftonline.com/organizations/adminconsent?client_id=44cc274e-8962-4fbb-9917-708ff8acffaf\&redirect_uri=https%3A%2F%2Fwww%2Ezenable%2Eapp%2Flogin) by clicking the link and granting consent.
Once the application is installed, users from your organization can sign in to
[zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=web\&utm_content=management-console) with their Microsoft Entra ID account by
selecting **Continue with Entra ID**:
In some cases, the login page displays **Email does not match any enterprise
directory** after you enter your email address. If this happens, select
**Continue with Entra ID** to sign in with Microsoft manually.
## OIDC Onboarding
Any identity provider that supports OpenID Connect can be used for SSO with Zenable. This includes Okta, Auth0, Keycloak, PingFederate, ForgeRock, WorkOS, and others.
### Use Cases
* **Interactive login** — Users authenticate via your IdP and get redirected to Zenable
* **Machine identities** — Agents, CI/CD pipelines, or automation tools authenticate programmatically using OIDC tokens issued by your IdP, without browser interaction
### Requirements
Your identity provider must:
* Support the OpenID Connect protocol
* Expose a discovery endpoint (`/.well-known/openid-configuration`) over HTTPS
* Be publicly reachable from the internet
### Setup Process
1. In your IdP, create a new OIDC client (confidential, with a client secret) with the following settings:
| Setting | Value |
| - | - |
| **Allowed redirect URI** | `https://zenable.us.auth0.com/login/callback` |
| **Allowed scopes** | `openid`, `profile`, `email` |
2. For M2M use cases, also enable the **client credentials grant** on the OIDC client so machines can obtain tokens without user interaction.
3. Contact us at [hello@zenable.io](mailto:hello@zenable.io) securely to initiate the setup. We will need:
```
OIDC Discovery URL:
Client ID:
Client Secret:
Email domain(s) (for interactive login):
```
Once we receive this information, we'll configure the connection on our end and notify you when SSO is ready.
### Okta
1. In the Okta administrator section choose Applications
2. On the app screen, select Create App Integration
3. Select "OIDC - OpenID Connect" and then "Web Application" in Application type
4. Fill a name for the application and select "Authorization Code" as the Grant type
5. In the "Sign-in redirect URIs" field, add `https://zenable.us.auth0.com/login/callback`
6. In "Assignments" fill in the groups that should have access to Zenable according to your organization's needs
7. Fill the rest of the fields as your organization requires and save the application
8. Send us the Okta Domain, Client ID, Client Secret, and email domain(s) used to log in
### Keycloak
1. Create a realm (or use an existing one)
2. Go to **Clients → Create client**, set type to OpenID Connect
3. Enable **Client authentication** (makes it confidential)
4. Enable **Service accounts roles** (for M2M client credentials)
5. In **Valid redirect URIs**, add: `https://zenable.us.auth0.com/login/callback`
6. In **Web origins**, add: `https://zenable.us.auth0.com`
7. Copy the **Client ID** and **Client Secret** (from the Credentials tab)
8. Your Discovery URL is: `https://your-keycloak-domain/realms/your-realm/.well-known/openid-configuration`
### Using Machine Identity (Token Exchange)
Once your M2M connection is configured, your CI/CD pipelines or automation tools can exchange tokens issued by your IdP for Zenable API tokens. This follows the [RFC 8693 OAuth 2.0 Token Exchange](https://datatracker.ietf.org/doc/html/rfc8693) standard.
After setup, we will provide you with:
* A `subject_token_type` URI unique to your organization (e.g., `https://zenable.app/oauth/your-org-token`)
Your IdP must be configured to issue tokens with the audience `https://www.zenable.app/`. Tokens without the correct audience will be rejected.
To exchange a token, make a `POST` request to `https://zenable.us.auth0.com/oauth/token` with the following parameters in the request body (`application/x-www-form-urlencoded`):
| Parameter | Value |
| - | - |
| `grant_type` | Always `urn:ietf:params:oauth:grant-type:token-exchange` |
| `subject_token` | A valid JWT from your IdP |
| `subject_token_type` | The URI we provide during onboarding |
| `client_id` | `BwZkedovVV2bIPmxmK3crzdHmTdRqjv4` |
| `audience` | `https://www.zenable.app/` |
Each unique `sub` (subject) claim in your tokens creates a separate user, and with that a seat. If you rotate or recreate your M2M client in your IdP, the new client will consume an additional seat. Contact us at [hello@zenable.io](mailto:hello@zenable.io) if this is a concern.
## What You Can Configure
Through the management console, you can:
* **Custom Requirements** ([zenable.app/requirements](https://www.zenable.app/requirements?utm_source=docs\&utm_medium=web\&utm_content=management-console)): Upload your architecture decisions, coding standards, and compliance requirements
* **Quality Guardrails** ([zenable.app/guardrails](https://www.zenable.app/guardrails?utm_source=docs\&utm_medium=web\&utm_content=management-console)): View and manage auto-generated guardrail code, with reliable review delivery
* **Scopes**: Control where requirements apply—by repository, organization, repository metadata, path pattern, file extension, user, group, or integration
* **AI Assistant**: Use the built-in chat to create requirements, iterate on guardrails, search across your configuration, and more
* **Detailed Findings** ([zenable.app/reports/findings](https://www.zenable.app/reports/findings?utm_source=docs\&utm_medium=web\&utm_content=management-console)): See what's happening in your environment; get a bird's eye view of findings with interactive charts and a full paginated findings table on a single page. Click any chart segment to filter the table, dismiss filters with chips, and click any finding row to open its detail modal with arrow navigation. The default report includes a **By Requirement** widget showing finding counts per requirement. Filter findings by category, repository, file path (glob patterns like `*.md` or `**/tests/*.py`), integration, user, or requirement. Full-detail findings are retained for 13 months
* **Agent Observability** ([zenable.app/reports/agent-observability](https://www.zenable.app/reports/agent-observability?utm_source=docs\&utm_medium=web\&utm_content=management-console)): See what your coding agents are actually doing across your environment. Headline counts (events, active users, repositories, tools, peak activity per hour) sit above an activity-over-time chart you can segment by action, IDE, repository, or user and bucket hourly or daily. Top-tool, -user, -repository, and -branch breakdowns show where the volume is, and an anomaly feed flags suspicious patterns like command bursts and volume spikes to drill into. A searchable, paginated events table lists individual tool calls—filter by action type, tool, IDE, repository, branch, user, or time range, and expand any row for its full input payload and per-session token usage.
[Learn more about requirements & guardrails →](/requirements-and-guardrails)
Once configured, these requirements automatically enforce in:
* Every developer's IDE
* Pre-commit hooks
* PR reviews
[Learn about Policy as Code →](/use-cases/policy-as-code)
## Get Started
Log in to configure requirements
Set up IDE quality guardrails
Automate code review
**Need help?** Contact us at [hello@zenable.io](mailto:hello@zenable.io)
# Marketplace
Source: https://docs.zenable.io/marketplace
Browse and manage curated requirement bundles and individual requirements
## Overview
The Zenable Marketplace is an opt-in catalog of governance requirements. Browse curated **bundles** or individual requirements, subscribe to the controls you need, and customize subscribed requirements without changing the publisher's definition.
Access the marketplace at [zenable.app/marketplace](https://www.zenable.app/marketplace?utm_source=docs\&utm_medium=web).
A subscription is one source of coverage. A requirement can also be covered by another bundle, an individual subscription, or a company-wide subscription. Removing one source does not deactivate a requirement that is still covered elsewhere.
## Browsing the Catalog
The **Browse** tab shows published bundles and individual requirements. A bundle is a curated, versioned collection of related requirements; subscribe to a bundle when you want the complete set, or subscribe to individual requirements when you only need specific controls.
Use the search, type, and category filters to narrow the catalog. Grid and list views show the publisher, version, category or bundle, and current subscription state. List columns are sortable.
To act on multiple items, hold Ctrl or Command while clicking to toggle items, or hold Shift to select a range. **Subscribe selected** and **Unsubscribe selected** skip items already in the requested state.
Requires the `marketplace:read` permission. See [Roles and Permissions](/permissions?utm_source=docs\&utm_medium=web) for details.
## Bundles
Bundles let you opt into a related set of requirements at once. Open a bundle to review its requirements and changelog before subscribing. Requirements that are already active are marked in the bundle, and **Hide subscribed** lets you focus on requirements the bundle would add.
Open a requirement inside a bundle to review its details or **Subscribe individually**. An individual subscription keeps that requirement active if you later unsubscribe from the bundle. Requirements can belong to multiple bundles, but Zenable includes each active requirement only once.
## Subscribing and Unsubscribing
Subscribe to bundles or individual requirements from the catalog. Requires the `marketplace:manage` permission (Professional tier and above).
Click **Subscribe** on a requirement or bundle, then choose where it applies:
* **This workspace** applies it only in the workspace you are currently viewing, with the scopes you choose.
* **All workspaces in my company** enforces it in every current and future workspace with the scope you choose. Only built-in scopes are available for company-wide requirements. This option requires `company:manage` and is available to Company Owners.
Subscribed requirements appear on the [requirements page](/requirements-and-guardrails). Connected review and IDE integrations evaluate them according to each requirement's scopes and enforcement settings.
A workspace can give a company-wide requirement its own scope with **Override scope here** on the Subscriptions tab, or from **Customize** on the requirement. That creates a workspace subscription for the same item, which replaces the company decision in that workspace only. Unsubscribing the override restores the company-wide scope there.
Use the **Subscriptions** tab to review company-wide subscriptions, workspace subscriptions, and workspace exceptions:
* **Enforce Company-Wide** changes a workspace subscription so every current and future workspace is subscribed, with the company-wide scope you choose in the confirmation.
* **Stop enforcing this subscription company-wide** keeps it subscribed in the current workspace, with the same scope, but stops other workspaces from inheriting it.
* **Edit scope** changes where a subscription applies in place. On a company subscription it edits the company-wide scope; on a workspace subscription it edits that workspace's scope.
* **Block Inheritance** stops an inherited company subscription from applying in the current workspace only.
* **Stop blocking inheritance** removes that workspace exception and restores company-wide enforcement there.
Before unsubscribing, Zenable previews the affected requirements and customizations. Unsubscribing removes that subscription source. Saved customizations remain available and become active again if another subscription covers the requirement later.
## Pinning and Extending
Subscriptions track the latest published versions by default. Pin versions when you need a stable baseline:
* **Pin a bundle** to keep its current set of requirements.
* **Pin a requirement** to keep its current definition and guardrails.
Bundle and requirement pins are independent. The **Updates** tab shows pinned content with newer versions available so you can review and update it when ready.
Customize a subscribed requirement from the requirements page without changing the marketplace definition. Workspace customizations remain separate from publisher updates and are retained if you unsubscribe.
## Permissions
| Permission | Description | Availability |
| - | - | - |
| `marketplace:read` | Browse the catalog, bundles, and requirements | Any tier |
| `marketplace:manage` | Subscribe, unsubscribe, pin, and customize marketplace content | Professional and above |
| `company:manage` | Manage company-wide subscriptions and workspace inheritance | Company Owner |
| `marketplace:publish` | Publish marketplace requirements and bundles | Enterprise publishers |
See the full [Roles and Permissions](/permissions?utm_source=docs\&utm_medium=web) matrix.
## Becoming a Publisher
Want to share your requirements with the Zenable community?
Email **[hello@zenable.io](mailto:hello@zenable.io)** to apply to become a marketplace publisher. We're particularly interested in organizations and project maintainers or power users who can contribute:
* Deterministic static analysis tool integrations
* Guardrail language implementations
* Security and compliance frameworks
* Industry-specific best practices
* Open source project guidelines
* Enterprise governance standards
## Next Steps
* [Browse the marketplace](https://www.zenable.app/marketplace?utm_source=docs\&utm_medium=web) to subscribe to bundles
* [View requirements and guardrails](/requirements-and-guardrails) in the management console
* [Install MCP](/integrations/mcp/getting-started) for IDE integration
* [Set up VCS reviewers](/integrations/vcs-reviewers/github) for automated enforcement
# Roles and Permissions
Source: https://docs.zenable.io/permissions
Control access with role-based permissions
## Overview
Zenable uses Role-Based Access Control (RBAC) to manage who can do what within your organization. The system follows these principles:
* **Permissions** are atomic actions (e.g., "edit requirements")
* **Roles** bundle permissions together (e.g., "Admin" has many permissions)
* **Users** are assigned roles directly or via identity provider groups
## Check your permissions from the CLI
Not sure whether you can do something? The [Zenable CLI](/integrations/zenable/commands?utm_source=docs\&utm_medium=web) answers it directly. `zenable auth can-i` prints `yes` or `no` (and sets a matching exit code, so it's scriptable) for any RBAC permission **or** MCP tool:
```bash Check a permission theme={null}
zenable auth can-i requirements:write
```
```bash Check an MCP tool theme={null}
zenable auth can-i get_findings
```
```bash List everything you can and cannot do theme={null}
zenable auth can-i --list
```
Every permission in the matrix below and every Zenable MCP tool is covered. `--list` shows them all at once with each one's grant status.
Don't have the CLI yet? See the [installation guide](/integrations/zenable/commands?utm_source=docs\&utm_medium=web#quick-installation).
## System Roles
Zenable provides six predefined roles that cover common access patterns:
| Role | Description | Key Capabilities |
| - | - | - |
| **Viewer** | Read-only access | View requirements, users, integrations, settings, marketplace catalog |
| **Contributor** | Create and edit content | All Viewer permissions + write/export requirements, subscribe to marketplace items |
| **Admin** | Full admin access (billing read-only) | All Contributor + manage users, roles, integrations, audit logs |
| **Owner** | Complete access | All Admin + billing management |
| **Billing Administrator** | Financial access | View everything + manage billing and invoices |
| **Security Auditor** | Audit + governance access | View/export audit logs, view requirements, guardrails, and governance |
Custom roles are available on Enterprise plans. Contact us to learn more.
## Groups
Groups are tenant-owned sets of users, created and managed on the [Groups tab in Company Settings](https://www.zenable.app/settings?tab=groups\&utm_source=docs\&utm_medium=web). They are referenced by `GROUP` requirement scopes (see [`groups:read` / `groups:write`](#groups)).
A group can also contain other groups, so a scope on a parent group reaches members of its nested teams.
Group nesting is capped at 3 levels deep; members nested below that are not included.
## RBAC Audit Logging
RBAC Audit logging is available on **Professional** and **Enterprise** plans only. Log exporting requires an **Enterprise** plan.
All role and permission assignments and revocations are logged for compliance, including any provided reason.
Audit logs cannot be deleted by users regardless of role.
Access audit logs via the **Audit** section in the management console or through the `audit:read` permission.
## Role Permission Matrix
| Permission | Viewer | Contributor | Admin | Owner | Billing Admin | Security Auditor |
| - | :-: | :-: | :-: | :-: | :-: | :-: |
| requirements:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| requirements:write | | ✓ | ✓ | ✓ | | |
| requirements:delete | | | ✓ | ✓ | | |
| requirements:export | | ✓ | ✓ | ✓ | | |
| context:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| context:write | | ✓ | ✓ | ✓ | | |
| scopes:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| scopes:write | | ✓ | ✓ | ✓ | | |
| groups:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| groups:write | | ✓ | ✓ | ✓ | | |
| guardrails:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| guardrails:write | | ✓ | ✓ | ✓ | | |
| findings:read | ✓ | ✓ | ✓ | ✓ | | |
| findings:manage | | ✓ | ✓ | ✓ | | |
| reports:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| reports:write | | ✓ | ✓ | ✓ | | |
| users:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| users:invite | | | ✓ | ✓ | | |
| users:remove | | | ✓ | ✓ | | |
| users:manage | | | ✓ | ✓ | | |
| users:manage\_seats | | | ✓ | ✓ | | |
| roles:read | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| roles:manage | | | ✓ | ✓ | | |
| billing:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| billing:manage | | | | ✓ | ✓ | |
| billing:view\_invoices | | | | ✓ | ✓ | |
| audit:read | | | ✓ | ✓ | | ✓ |
| audit:export | | | ✓ | ✓ | | ✓ |
| governance:read | ✓ | ✓ | ✓ | ✓ | | ✓ |
| governance:manage | | | ✓ | ✓ | | |
| governance:delete | | | ✓ | ✓ | | |
| integrations:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| integrations:manage | | | ✓ | ✓ | | |
| integrations:link\_self | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| settings:read | ✓ | ✓ | ✓ | ✓ | ✓ | |
| settings:manage | | | ✓ | ✓ | | |
| learning\_hub:read | ✓ | ✓ | ✓ | ✓ | | |
| learning\_hub:sandbox | ✓ | ✓ | ✓ | ✓ | | |
| feature\_flags:read | | | ✓ | ✓ | | |
| feature\_flags:manage | | | ✓ | ✓ | | |
| marketplace:read | ✓ | ✓ | ✓ | ✓ | | |
| marketplace:manage | | ✓ | ✓ | ✓ | | |
| marketplace:publish | | | | | | |
| requirements:approve | | ✓ | ✓ | ✓ | | |
| guardrails:approve | | ✓ | ✓ | ✓ | | |
| approvals:read | ✓ | ✓ | ✓ | ✓ | | |
| approvals:feedback | | ✓ | ✓ | ✓ | | |
| approvals:manage | | | ✓ | ✓ | | |
| feedback:read | | ✓ | ✓ | ✓ | | |
| feedback:write | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
| company:manage | | | | ✓ | | |
## Permissions by Category
### Requirements
| Permission | Description |
| - | - |
| `requirements:read` | View and search requirements |
| `requirements:write` | Create and edit requirements |
| `requirements:delete` | Permanently delete requirements and associated guardrails |
| `requirements:export` | Export requirements to external formats |
Deleting a requirement is permanent and also deletes all guardrails associated with that requirement. This action cannot be undone.
### Context
| Permission | Description |
| - | - |
| `context:read` | View reviewer contexts at customer and tenant levels |
| `context:write` | Create, edit, and delete reviewer contexts |
### Scopes
| Permission | Description | Minimum Tier |
| - | - | - |
| `scopes:read` | View scope definitions | Professional |
| `scopes:write` | Create, edit, and delete scope definitions, and cast a binding decision on scope [approval requests](/approval-workflows#who-can-decide-what) | Professional |
### Groups
| Permission | Description | Minimum Tier |
| - | - | - |
| `groups:read` | View groups and their members | Professional |
| `groups:write` | Create, edit, and delete groups and manage their members, and cast a binding decision on group [approval requests](/approval-workflows#who-can-decide-what) | Professional |
Groups are tenant-owned sets of users referenced by `GROUP` requirement scopes. They are gated like scopes, since they're only useful via scoping.
### Guardrails
| Permission | Description | Minimum Tier |
| - | - | - |
| `guardrails:read` | View guardrails | Professional |
| `guardrails:write` | Create, edit, and delete guardrails | Professional |
### Findings
| Permission | Description | Minimum Tier |
| - | - | - |
| `findings:read` | View code review findings and resolutions | Professional |
| `findings:manage` | Create, update, and resolve findings | Professional |
### Reports
| Permission | Description |
| - | - |
| `reports:read` | View assessment reports |
| `reports:write` | Upload assessment reports |
### Users
| Permission | Description |
| - | - |
| `users:read` | View team members |
| `users:invite` | Invite new users |
| `users:remove` | Remove users from tenant |
| `users:manage` | Assign and revoke roles, and link third-party identities (e.g. GitHub or GitLab accounts) to users |
| `users:manage_seats` | Release and reassign seat licenses for users in tenant |
### Roles
| Permission | Description |
| - | - |
| `roles:read` | View custom roles and their permissions |
| `roles:manage` | Create, edit, delete, promote, and demote custom roles |
### Billing
| Permission | Description |
| - | - |
| `billing:read` | View billing information |
| `billing:manage` | Modify subscription |
| `billing:view_invoices` | Download invoices |
### Audit
| Permission | Description | Minimum Tier |
| - | - | - |
| `audit:read` | View audit logs | Professional |
| `audit:export` | Export audit logs | Enterprise |
### Governance
| Permission | Description | Minimum Tier |
| - | - | - |
| `governance:read` | View governance domains and evidence | Professional |
| `governance:manage` | Create and edit governance domains and map requirements to them | Professional |
| `governance:delete` | Delete governance domains from the tenant taxonomy | Professional |
Deleting a governance domain is permanent. Requirements mapped to the domain must be reassigned or explicitly unmapped as part of the deletion flow.
### Integrations
| Permission | Description |
| - | - |
| `integrations:read` | View configured integrations |
| `integrations:manage` | Add, remove, configure integrations |
| `integrations:link_self` | Link your own GitHub or GitLab account to your Zenable user, one per integration, from your profile. Linking someone else's requires `users:manage` |
### Settings
| Permission | Description |
| - | - |
| `settings:read` | View tenant settings |
| `settings:manage` | Modify tenant configuration, and cast a binding decision on guardrail runtime-settings and configuration-proposal [approval requests](/approval-workflows#who-can-decide-what) |
### Learning Hub
| Permission | Description |
| - | - |
| `learning_hub:read` | View Learning Hub training content: workshops, labs, and slide decks. Individual content can additionally require a subscription tier |
| `learning_hub:sandbox` | Launch a personal sandbox environment (bounded by the customer's sandbox limits), view session status, and connect to assigned environments. Bulk or scheduled sessions additionally require `settings:manage` |
### Feature Flags
| Permission | Description |
| - | - |
| `feature_flags:read` | View feature flags |
| `feature_flags:manage` | Enable/disable feature flags |
### Marketplace
| Permission | Description | Minimum Tier |
| - | - | - |
| `marketplace:read` | Browse marketplace catalog, bundles, and requirements | — |
| `marketplace:manage` | Subscribe, unsubscribe, pin, and customize marketplace items for a workspace | Professional |
| `marketplace:publish` | Publish new versions of marketplace requirements | Enterprise |
### Approvals
| Permission | Description | Minimum Tier |
| - | - | - |
| `requirements:approve` | Cast a binding approve/reject decision on requirement proposals, including merges and splits | Professional |
| `guardrails:approve` | Cast a binding approve/reject decision on guardrail regeneration and custom-guardrail requests | Professional |
| `approvals:read` | View approval flows, pending requests, and the full feedback thread (everything is transparent — no per-record hiding) | Professional |
| `approvals:feedback` | Submit non-binding feedback (vote up/down, add commentary) on an approval request | Professional |
| `approvals:manage` | Create, edit, and archive approval flow definitions, [approval policies](/approval-policies), and target selectors — the approval machinery, not the changes it gates | Professional |
Learn more about [approval workflows](/approval-workflows).
### Feedback
| Permission | Description |
| - | - |
| `feedback:read` | View feedback |
| `feedback:write` | Submit feedback |
### Company
| Permission | Description |
| - | - |
| `company:manage` | Manage company-wide settings that apply across every tenant (owner only) |
**Need help?** Contact us at [hello@zenable.io](mailto:hello@zenable.io)
# Plans and Usage
Source: https://docs.zenable.io/plans-and-usage
Compare Zenable's Free, Pro, and Enterprise plans and learn how usage, seats, and billing work.
## Plans Overview
The Free plan is designed for individual developers getting started.
* 2-Click Setup
* Automated PR Summaries
* Documentation
* API Access
[Get started for free](https://zenable.io/github?utm_source=docs\&utm_medium=web) — no credit card required.
The Professional plan is for teams that need guardrails, custom requirements, and higher limits.
* Everything in Free
* Team Management
* Custom Guardrails for AI IDEs
* PR Guardrails (custom requirements)
* Ensure AI Follows Your Requirements
* Onboarding Support
* Training Videos
[Start a 14-day free trial](https://zenable.app?trial=true\&utm_source=docs\&utm_medium=web) — no credit card required.
Enterprise is for organizations with 100+ developers that need dedicated infrastructure, custom terms, and higher limits.
* Everything in Professional
* Dedicated Runtime Environment
* Dedicated Customer Success Manager
* Custom Branding
* Negotiable Terms of Service
[Contact us](mailto:hello@zenable.io?subject=Zenable%20Enterprise) to discuss Enterprise pricing.
For a side-by-side plan comparison, see the [Pricing page](https://zenable.io/pricing?utm_source=docs\&utm_medium=web).
## Usage Limits
| | Free | Professional | Enterprise |
| - | - | - | - |
| Zenable Credits | 5,000/week (per seat) | 200,000/week (per seat) | 800,000/week (per seat) |
## How Reviews Work
AI-powered reviews consume credits each time a file is reviewed. Coding-agent checks and PR/MR reviews share one per-seat credit pool. Guardrails (deterministic reviews and static analysis) have unlimited usage but are subject to capacity-based rate limiting and abuse prevention.
An agentic IDE writes code using Claude Code, Cursor, VS Code, or any [supported IDE](/integrations/mcp/getting-started#supported-ides).
Zenable identifies files that changed between the start and end of the agentic IDE's work and queues them for review.
Files matching your [skip patterns](https://www.zenable.app/settings?utm_source=docs\&utm_medium=web) are removed from the queue. The remaining files are reviewed.
If multiple branches were touched during that agentic loop, each is reviewed independently and findings are passed back to the agentic IDE per branch.
At the end of the agentic IDE's workload, if there are findings from the review, those are passed back and work continues. Only additional file changes after this point are re-reviewed.
If the agentic IDE makes no additional changes, nothing additional is reviewed, and it stops.
### Credit Cost Per File
Each AI-model review consumes credits based on your model tier and the file size; Guardrails
and static checks are free.
| Check Type | Credits |
| - | - |
| Guardrails & static checks | **0** (unlimited) |
| Standard AI model | **10** per file |
| Premium AI model | **25** per file |
Configure your AI model tier in [company settings](https://www.zenable.app/settings?utm_source=docs\&utm_medium=web).
#### Large files
Most files fit a single **30,000-character** review. Larger files are still
reviewed in full as **jumbo files** — the review scales to the file, and so
does the credit cost. A large file gets a deeper, more context-heavy review,
so jumbo files are priced at **2× their size**.
A jumbo file is measured in 30,000-character chunks, and the cost is 2× that chunk count
applied to your per-file rate above:
| File size | Review size | Credit cost |
| - | - | - |
| up to 30,000 chars | 1× (standard) | base (10 or 25) |
| up to 60,000 chars | 2× | 4× base |
| up to 90,000 chars | 3× | 6× base |
| … | … | … |
| up to 300,000 chars | 10× | 20× base |
Jumbo reviews are itemized on the usage dashboard, so you can see exactly
which files were jumbo and at what multiple. The largest reviewable file is
**300,000 characters** (10×); larger files are noted in the review summary.
These limits may change.
The in-app chat assistant and the Zenable MCP server expose the same set of
tools for managing requirements, guardrails, and scopes. Read tools cost a
flat 10 credits; write tools cost more. All of these tools deduct from the
**same weekly per-seat Zenable Credits pool** as coding-agent conformance
checks and PR/MR bot reviews.
### Credit Cost Per Tool Call
| Tool | Credits | Direction |
| - | - | - |
| `get_requirements` | **10** | Read |
| `get_guardrails` | **10** | Read |
| `get_scopes` | **10** | Read |
| `get_findings` | **10** | Read |
| `get_agent_feedback` | **10** | Read |
| `get_human_feedback` | **10** | Read |
| `create_scope` | **10** | Write |
| `reinstate_prior_guardrail_version` | **10** | Write |
| `create_requirement` | **25** | Write |
| `regenerate_guardrail` | **550** | Write |
Write tools require a Professional plan or an active trial. Free-tier
users without a trial can use the read tools but not the write tools.
### Guardrail Regeneration
Running a guardrail free and unlimited on all plans; generating a guardrail costs 550 credits.
| Action | Credits |
| - | - |
| Enforcing a guardrail (CLI, hooks, IDE, PR reviews) | **0** — unlimited on every plan, including Free |
| Generating a new guardrail version — `regenerate_guardrail`, **Regenerate now** on the guardrail page, or automatic self-healing after a runtime failure | **550** per regeneration |
The usage dashboard breaks activity out so you can see how much of your
weekly pool went to coding-agent scans vs. chat/MCP requirement management,
even though they share the same counter.
PR Bot Reviews are triggered automatically when a pull/merge request is opened on GitHub or GitLab. They are priced **per reviewed file**, from the same credit rate card as every other AI review — small PRs cost little, and a PR whose files are all skipped costs nothing.
Reviews are billed to the PR author's per-seat credit pool. The author's
GitHub or GitLab account must be linked to their Zenable user (Settings →
User Management); on paid plans, unlinked authors share a per-installation
pool with one seat's worth of credits, and on the Free plan unlinked
authors are prompted to link before reviews run.
As of September 6, 2026, all usage reporting is credit-based. Before that
date, usage plans used a mix of credits and PR/MR review counts. For usage
details from before September 6, 2026, contact
[hello@zenable.io](mailto:hello@zenable.io).
On GitHub or GitLab, a pull/merge request is created.
Codebase explore agents research impact and gather context. Branch patterns can be excluded (e.g. Dependabot and other automated maintenance PRs) from reviews automatically in [company settings](https://www.zenable.app/settings?utm_source=docs\&utm_medium=web).
Each reviewed file costs **25 credits**, scaled by the same
[jumbo multiplier](#large-files) as other AI reviews (measured on the
file's content plus its diff). Skipped files — skip patterns, the
per-PR file cap, oversized files — cost nothing.
If a PR is closed and reopened, or a review is re-requested via a `/zenable` comment, the new review is charged again for the files it reviews.
### Review Limits
| Limit | Value | Behavior |
| - | - | - |
| Files per PR | 150 | Files beyond the limit are skipped. The review completes for the remaining files and a notice is added suggesting to split the PR. |
| File size | 300,000 characters | Files whose combined content and diff exceed the jumbo ceiling are skipped. The review completes for the remaining files and a notice is added suggesting to break the file into smaller pieces. |
These limits are subject to change.
Skipped files are reported in a collapsed section of the review summary so you know exactly what was and wasn't reviewed.
Branches or files can be excluded from review using skip patterns (e.g. Dependabot PRs, lock files) on the [settings page](https://www.zenable.app/settings?utm_source=docs\&utm_medium=web).
## Credit Usage Examples
Your IDE's MCP server sends a conformance check with **3 files**. No exclusions match.
* Standard: 10 × 3 = **30 credits**
* Premium: 25 × 3 = **75 credits**
`zenable check "**/*.py"` finds **10 files**. Your config excludes `generated.py`, so **9** are checked. You have 25 guardrails that apply to all `.py` files.
* Guardrails: 25 × 0 = **0 credits**
* Standard: 10 × 9 = **90 credits**
* Premium: 25 × 9 = **225 credits**
A hook runs on commit with **5 changed files**. Two match exclusion patterns, so **3** are reviewed.
* Standard: 10 × 3 = **30 credits**
* Premium: 25 × 3 = **75 credits**
Your agentic IDE touches files across two branches in one session. On `feat/a`, it changes `auth.py`, `utils.py`, and `config.py`. It then switches to `feat/b` and changes `utils.py` and `api.py`. Even though `utils.py` was touched on both branches, each branch is reviewed independently — 3 files on `feat/a`, 2 files on `feat/b`.
* Standard: 10 × 5 = **50 credits**
* Premium: 25 × 5 = **125 credits**
You ask the in-app chat assistant to find an existing requirement and, not
finding a match, it creates a new one on your behalf.
* `get_requirements`: 10 credits
* `create_requirement`: 25 credits
* **Total: 35 credits**
You open a PR with **6 changed files**. One matches your skip patterns, so
**5** are reviewed, all under 30,000 characters.
* 25 × 5 = **125 credits**, billed to the PR author's seat
Your AI coding assistant identifies a flaky Semgrep guardrail and calls the
MCP server to regenerate it with your feedback.
* `get_guardrails`: 10 credits
* `regenerate_guardrail`: 550 credits
* **Total: 560 credits**
Every run of the regenerated guardrail afterward — in your hook, the CLI,
or a PR review — costs nothing.
## How Credits Refresh
If you exhaust your AI review credits, AI-powered reviews pause until your next weekly credit reset. Guardrails and static checks continue to run.
If a PR's estimated cost exceeds the author's remaining weekly credits, Zenable leaves a comment on the PR indicating that the limit has been reached and the review was not performed — nothing is charged for a withheld review.
| Cadence | Applies to | Resets at |
| - | - | - |
| Weekly | Zenable Credits (all surfaces) | Monday 00:00 UTC |
Track your credit usage on the [billing dashboard](https://www.zenable.app/billing?utm_source=docs\&utm_medium=plans-and-usage) — per-seat usage, PR/MR review activity, and weekly trends.
# Proposals
Source: https://docs.zenable.io/proposals
Triage proposed requirements and guardrails by scope or by person
## Overview
**Proposals** is the triage queue for *proposed* changes — requirements and guardrails Zenable has recommended but that haven't been accepted yet. It helps you refine those recommendations to cut noise and uphold your standards, and it routes each recommendation to whoever should act on it.
The same work can be viewed through two lenses, toggled at the top of the page:
| Lens | Groups recommendations by… | Use it to answer |
| - | - | - |
| **Scopes** | **Where** the work applies — a repo, path pattern, package, or the CLI (the recommendation's scope) | "What's outstanding in *this* part of my codebase?" |
| **People** | **Who** is responsible — the scope's owners plus anyone a recommendation is assigned to | "What's on *this person's* plate?" |
Both lenses read the same underlying recommendations; switching the toggle only changes how they're grouped — it never changes the counts.
## Status cards
Three cards at the top summarize the whole tenant and act as filters. Click one to filter the cards below by that status (click again to clear):
| Card | Meaning |
| - | - |
| **Total** | Every open or pending recommendation across all scopes |
| **Open** | Proposed recommendations not yet in an approval flow |
| **Pending Human Approval** | Recommendations whose change is waiting on an [approval workflow](/approval-workflows) decision |
Recommendations that have been **resolved** (accepted or declined) leave the queue — Proposals is a work list, not a history.
## Scopes
Each **scope** card shows the scope's name, its open / pending counts, and its **owners**. Open a card to see the linked recommendations, assign them, and triage each one.
### Owners
A scope can be owned by a [Group](/permissions). The group's current members surface as the scope's **owners**, so everyone can see who's accountable for a part of the codebase. Owners are set wherever a scope is created or edited — including the **Owners** picker in the scope edit form on the [Requirements → Scopes](/requirements-and-guardrails) tab — and changing the owning group takes effect immediately (membership is live; no re-approval).
### Quality score
Each recommendation carries a **quality score** (0–10) shown as a color-coded number in the recommendations table:
| Color | Range | Meaning |
| - | - | - |
| Green | 7 and above | High-confidence, high-priority recommendation |
| Amber | 4–6.9 | Moderate confidence |
| Red | Below 4 | Speculative; review before accepting |
The table defaults to sorting by quality score descending so the most actionable work surfaces first. Click the column header to reverse the sort.
## People
The **People** lens inverts the same data: each card shows the recommendations owned by that person or group (through a scope they're an owner of) or that are directly assigned to them. Use the **Assigned to me** button to jump straight to your own queue.
Group rows appear alongside individual people. Each group card shows the group's member chips and aggregates all scopes the group owns; clicking a group row drills into the group's full responsibility view.
### Assignment
Within a scope you can assign individual recommendations to a teammate or a [Group](/permissions). Assigning to a group fans out to every member — the recommendation appears on each member's People card and in their per-person counts.
## View as a list
The **View as a list** link switches from the grouped card view to a flat, sortable table of every recommendation — handy when you'd rather scan or bulk-act across scopes instead of drilling in one scope at a time.
## Related
* [Requirements and Guardrails](/requirements-and-guardrails) — what recommendations propose, and the Scopes tab where owners are set
* [Approval Workflows](/approval-workflows) — how Pending Human Approval recommendations get decided
* [Permissions](/permissions) — Groups, which back scope ownership and group assignment
# Requirements & Guardrails
Source: https://docs.zenable.io/requirements-and-guardrails
Define requirements, review auto-generated enforcement code, and visualize governance dependencies in the web console
## Overview
The Zenable management interface defines quality, functional, and security requirements, allows you to review and refine generated guardrail code, and
analyze relationships between requirements and enforcement points. Get started at [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=requirements-guardrails\&utm_content=get-started).
**What you can do:**
* Upload policy documents or define requirements directly
* Review auto-generated guardrail code (Terraform, K8s, Semgrep, etc.)
* Visualize governance graph to understand requirement dependencies
* Enable/disable specific guardrails for your environment
## Requirements
Define what needs to be enforced in your codebase at [zenable.app/requirements](https://www.zenable.app/requirements?utm_source=docs\&utm_medium=requirements-guardrails\&utm_content=requirements).
Upload documents like design documents, product requirements, or security policies and Zenable will automatically extract the requirements and
generate deterministic guardrails and specialized AI context for enforcement (patent pending).
Add, edit, enable/disable, and delete requirements, and optimize for various lifecycle stages including design, build, deploy, and runtime
enforcement.
Select one or more requirements and choose **Actions** to schedule refinement for the next nightly analysis window.
Visualize and analyze the relationships between your requirements, regulations, and technical controls with our patent pending requirements and
governance graph.
Open the version history modal on any requirement and switch to the **Lineage** view to see the full split and merge ancestry as a scrollable DAG. Each node represents a requirement family with its version history; hover for details, click to open that requirement.
## Guardrails as Code
Guardrails are **deterministic code** generated to enforce each requirement. Every requirement produces one or more guardrails depending on the
requirement type and applicable enforcement engines (Semgrep, CodeQL, Checkov, AWS SCP, Azure Policy, etc.).
View and manage generated guardrails at [zenable.app/guardrails](https://www.zenable.app/guardrails?utm_source=docs\&utm_medium=requirements-guardrails\&utm_content=guardrails).
### How Guardrails Work
1. **You define a requirement** — e.g., "All S3 buckets must have encryption enabled"
2. **Zenable generates guardrails** — deterministic rules for each applicable engine and lifecycle stage
3. **Guardrails enforce automatically** — via IDE suggestions, PR reviews, pre-commit hooks, or cloud policy enforcement
### Supported Engines
| Engine | Format | Use Case |
| - | - | - |
| **[Semgrep](/integrations/guardrails/semgrep)** | YAML rules | Static analysis patterns across many languages |
| **[CodeQL](/integrations/guardrails/codeql)** | QL queries | Deep semantic code analysis |
| **[Kyverno](/integrations/guardrails/kyverno)** | YAML policies | Kubernetes admission control |
| **[OPA / Gatekeeper](/integrations/guardrails/gatekeeper)** | Rego policies | General policy-as-code, K8s admission |
| **[Conftest](/integrations/guardrails/conftest)** | Rego policies | Configuration file testing (Terraform, K8s manifests, Dockerfiles) |
| **[Checkov](/integrations/guardrails/checkov)** | Python checks | Infrastructure-as-code static analysis |
| **[ESLint](/integrations/guardrails/eslint)** | JSON config | JavaScript/TypeScript linting |
| **[AWS SCP](/integrations/guardrails/aws-scp)** | JSON policies | AWS Organization-wide service control |
| **[Azure Policy](/integrations/guardrails/azure-policy)** | JSON definitions | Azure resource governance |
| **[Kubernetes VAP](/integrations/guardrails/kubernetes-vap)** | CEL expressions | Native K8s ValidatingAdmissionPolicies |
| **[Goss](/integrations/guardrails/goss)** | YAML tests | Server and container state validation |
### Example: Requirement to Guardrail
Given the requirement **"All S3 buckets must have server-side encryption enabled"**, Zenable generates engine-specific guardrails:
```yaml Semgrep theme={null}
rules:
- id: s3-encryption-required
patterns:
- pattern: |
resource "aws_s3_bucket" $BUCKET {
...
}
- pattern-not-inside: |
resource "aws_s3_bucket_server_side_encryption_configuration" $_ {
...
rule {
...
}
}
message: S3 bucket $BUCKET is missing server-side encryption configuration
severity: ERROR
languages: [hcl]
```
```json AWS SCP theme={null}
{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "DenyUnencryptedS3PutObject",
"Effect": "Deny",
"Action": "s3:PutObject",
"Resource": "*",
"Condition": {
"StringNotEquals": {
"s3:x-amz-server-side-encryption": "aws:kms"
}
}
}
]
}
```
```python Checkov theme={null}
from checkov.common.models.enums import CheckCategories, CheckResult
from checkov.terraform.checks.resource.base_resource_check import BaseResourceCheck
class S3BucketEncryption(BaseResourceCheck):
def __init__(self):
super().__init__(
name="Ensure all S3 buckets have server-side encryption enabled",
id="CKV_ZENABLE_1",
categories=[CheckCategories.ENCRYPTION],
supported_resources=["aws_s3_bucket_server_side_encryption_configuration"],
)
def scan_resource_conf(self, conf):
rule = conf.get("rule")
return CheckResult.PASSED if rule else CheckResult.FAILED
check = S3BucketEncryption()
```
### Guardrail Lifecycle
* **Versioning** — each guardrail tracks the requirement version it was generated from and its build iteration
* **Regeneration** — provide feedback and regenerate; Zenable improves the next iteration while preserving any historical context
* **Runtime status** — each guardrail carries a runtime status (valid, invalid, or untested) reported by whatever runs it against its target engine: the CLI, or Zenable's own checks. An invalid report is always recorded and shown on the guardrail page, whatever the settings below
* **When this guardrail is reported invalid** — a per-guardrail setting that decides whether the CLI **stops running it** (the default) or **keeps running it**. It changes only whether the rule runs; the guardrail still shows as reported invalid either way
* **Auto-healing** — a guardrail reported invalid is regenerated automatically by default, but can be disabled. This setting is independent of whether the guardrail stops or keeps running. Each attempt learns from every prior failed attempt in the episode (the rule and the exact error it produced)
* **Regenerate now** — request an immediate regeneration on the guardrail page, alongside up to 2,000 characters of context in your request
Enforcing guardrails is free and unlimited on every plan, including Free.
Generating a new version — by feedback, **Regenerate now**, or auto-healing —
costs **550 credits** per regeneration from the requesting user's weekly pool.
See [Plans and Usage](/plans-and-usage#guardrail-regeneration).
### Hybrid Approach: Deterministic + AI
Zenable uses **both** deterministic static analysis rules and AI-powered guardrails to achieve hallucination-resistant, highly accurate enforcement
(patent pending). This combination provides:
* **Deterministic rules** for well-defined patterns (AST analysis, policy-as-code, highly refined regular expressions)
* **AI guardrails** for complex semantic analysis and context-aware validation
* **Hallucination-resistant findings** by leveraging strengths of each approach
* **High accuracy** with reduced false positives and negatives
### Performance and Customization
Zenable's Guardrails are optimized for speed and customization, leveraging highly fine-tuned models with context-specific training for different
environments and stages of the SDLC.
## Scoping Requirements
Scopes decide **where** a requirement applies; a requirement attached to
multiple scopes applies when **any** of them matches. Path patterns are
glob expressions (`packages/api/**`, `**/*.py`) relative to the git repo
root — outside a git repo they are compared to the absolute file path —
and user conditions take an email or a GitHub/GitLab username, matching
the person across every login method and linked account.
### Repository Metadata Conditions
Scopes can also match repositories by their **metadata** — the
[custom properties](https://docs.github.com/en/organizations/managing-organization-settings/managing-custom-properties-for-repositories-in-your-organization)
your GitHub organization defines centrally (for example `team`,
`tier`, or `compliance`). Zenable keeps each repository's properties in
sync automatically: on installation, when repository access or property
values change, and from repository metadata included in pull request events.
A metadata condition has three parts — a property **key**, an
**operator**, and (for most operators) a **value**:
| Condition | Matches repos where… |
| - | - |
| `team` **is** `payments` | the `team` property equals `payments` |
| `tier` **is not** `sandbox` | the `tier` property is set, and no value equals `sandbox` |
| `compliance` **contains** `pci` | any `compliance` value contains `pci` |
| `team` **exists** | a `team` property has a value |
| `team` **does not exist** | no `team` property is set |
Keys and values support basic `*` and `?` wildcards (`t?er` **is**
`prod*`), matching is case-insensitive, and multi-select properties
match when **any** selected value satisfies the condition. Combine
metadata conditions with repository, organization, and other rules
using the standard AND/OR/NOT rule builder.
Absence is not a value. Negative operators (**is not**, **does not
contain**) require the property to be set, so a repository with no `tier`
property does **not** match `tier` **is not** `sandbox`. To include
untagged repositories, OR in a **does not exist** condition. Repositories
with no metadata at all — including every GitLab project, since GitLab
custom properties aren't ingested yet — match only **does not exist**.
### Integration Conditions
Scopes can target a specific integration, turning a requirement on or off
for one part of your toolchain:
* **All GitHub installations** or **All GitLab installations** — applies
to that provider's PR/MR reviews.
* **A single installation** — applies only to reviews from that one
GitHub App or GitLab installation.
* **Zenable CLI/IDE** — applies to `zenable check`, pre-commit, and IDE
hook runs.
## Requirement Usage & Findings
Track how requirements impact your codebase through the [Findings Analysis](https://www.zenable.app/analysis/findings?utm_source=docs\&utm_medium=web\&utm_content=requirements-guardrails) page:
* **Requirement filtering** — filter findings by the requirement that influenced them to understand each requirement's impact; filtering is performed at the database level for fast results even with large datasets
* **Findings count** — each requirement displays how many findings it has influenced, helping you gauge adoption and effectiveness
* **Cross-navigation** — jump from a requirement directly to its related findings, or from a finding to the requirements that influenced it
* **Report widgets** — add "findings by requirement" widgets to your dashboard to visualize requirement coverage across repositories
## Integrations with CLI and IDE Tools
* **Zenable CLI**: Install and manage the MCP server, configure IDE hooks, run one-off checks, and access other helper utilities
* **MCP Integration**: IDE suggestions updated in real-time via WebSocket
* **GitHub**: PR reviews enforce latest requirements ([GitHub integration](/integrations/vcs-reviewers/github))
* **GitLab**: MR reviews enforce latest requirements ([GitLab integration](/integrations/vcs-reviewers/gitlab))
* **Pre-commit Hooks**: Local validation uses synced requirements
## Next Steps
* [Install MCP](/integrations/mcp/getting-started) for IDE integration
* [Set up GitHub reviewer](/integrations/vcs-reviewers/github) or [GitLab reviewer](/integrations/vcs-reviewers/gitlab) for automated PR/MR reviews
* [Configure pre-commit hooks](/integrations/pre-commit/getting-started) for local enforcement
* [Review CLI documentation](/integrations/zenable/commands) for programmatic access
# Use Cases
Source: https://docs.zenable.io/use-cases
Real-world applications of the Zenable platform
Zenable transforms how organizations approach software governance. **Upload your requirements once**, and we automatically extract, understand, and enforce them throughout your entire development lifecycle.
## How It Works
1. **Upload Your Documents** - Policies, compliance frameworks, design docs, contracts
2. **Automatic Extraction** - We identify and structure all requirements
3. **Continuous Enforcement** - Every line of code, every PR, every developer action is checked
## Development & AI Safety
**Challenge**: AI coding assistants generate vulnerable code with security flaws and compliance violations
**Solution**: Real-time safety net that catches SQL injections, hardcoded secrets, and policy violations as code is written
**Result**: Ship AI-accelerated code with confidence - zero security compromises
[Explore AI safety features →](/use-cases/preventing-ai-mistakes)
**Challenge**: Rapid AI-driven development introduces inconsistent patterns and technical debt
**Solution**: Automated governance checks ensure every AI-generated feature meets your standards
**Result**: 10x development speed without sacrificing code quality
[See implementation details →](/use-cases/ai-tools-new-features)
**Challenge**: Bugs slip through reviews and automated testing misses edge cases
**Solution**: AI-powered analysis identifies subtle bugs and suggests fixes before production
**Result**: Fewer production incidents
[Learn bug prevention strategies →](/use-cases/finding-fixing-bugs)
## Code Assessment & Modernization
**Challenge**: Understanding and modernizing existing systems requires months of manual analysis
**Solution**: Automated deep-dive analysis maps dependencies, identifies risks, and creates implementation roadmaps
**Result**: Complete understanding of tech debt in hours, not months
[Start your assessment →](/use-cases/code-assessment)
**Challenge**: Security vulnerabilities hide in complex codebases and evolve with new threats
**Solution**: Continuous security scanning with context-aware vulnerability detection and remediation
**Result**: Proactive security posture with significant reduction in vulnerabilities reaching production
[Enhance security posture →](/use-cases/security-assessment)
## Compliance & Governance
**Challenge**: Audit preparation is stressful, manual, and reveals surprises at the worst time
**Solution**: Upload your framework (SOC 2, HIPAA, FedRAMP, etc.) and governance to get continuous compliance monitoring directly in your SDLC
**Result**: Pass audits on the first attempt with zero surprises
[Prepare for audits →](/use-cases/compliance-pre-audit)
**Challenge**: Translating governance policies into enforceable technical controls is error-prone
**Solution**: Automatic conversion of policies to executable rules with version control and testing
**Result**: 100% policy enforcement with full traceability
[Automate policy enforcement →](/use-cases/policy-as-code)
**Challenge**: Dependencies change frequently and are nearly impossible to manage
**Solution**: Monitor dependency changes, detect suspicious packages, prevent lookalike attacks, monitor for unwanted behavior / insider threats
**Result**: Protected supply chain and significant reduction in insider threat risk
[Secure your dependencies →](/use-cases/supply-chain-security)
## Project Lifecycle
**Challenge**: New projects start without proper governance setup, creating technical debt from day one
**Solution**: Automated project scaffolding with built-in governance, security, and compliance
**Result**: Projects start right with zero governance debt
[Launch correctly →](/use-cases/starting-new-project)
## Pricing & Plans
**Free Tier**: 5,000 Zenable credits/seat/week across PR reviews, agentic code reviews, and chat tools
**Professional**: Custom guardrails + higher limits
**Enterprise**: Customizable limits, dedicated support, isolated workloads
[Compare plans →](https://zenable.io/pricing?utm_source=docs\&utm_medium=use-cases\&utm_content=compare-plans)
## Getting Started
See Zenable in action for your specific needs
Start with real-time IDE feedback today
Automate your GitHub PR reviews immediately
Automate your GitLab MR reviews immediately
Discuss enterprise requirements
# AI Tools & New Features
Source: https://docs.zenable.io/use-cases/ai-tools-new-features
Automated governance checks ensure every AI-generated feature meets your standards
## Overview
Rapid AI-driven development introduces inconsistent patterns and technical debt. Zenable provides automated governance checks that ensure every AI-generated feature meets your standards, enabling 10x development speed without sacrificing code quality.
## Out-of-the-Box Quality Checks
Zenable automatically enforces these standards on AI-generated features:
* **Security Best Practices** - Authentication, authorization, input validation
* **Performance Patterns** - Efficient queries, caching, async operations
* **Error Handling** - Proper exceptions, logging, recovery
* **Code Organization** - SOLID principles, clean architecture
* **API Consistency** - RESTful patterns, response formats
* **Testing Requirements** - Unit tests, integration tests
## Custom Feature Requirements
Enforce your organization's specific feature patterns:
> "All new features must use our feature flag system, include telemetry events, follow our domain-driven design patterns, and integrate with our custom analytics pipeline."
## In Action
When you use AI to build features, Zenable:
1. Validates against standard quality checks
2. Enforces your custom requirements
3. Provides instant feedback to the AI
4. Ensures consistent implementation
## Custom Feature Examples
### Example: Feature Flag Integration
**Your Policy:** "All new features must be wrapped in feature flags with gradual rollout"
```python theme={null}
# ❌ AI generates without feature flags
@app.post("/new-feature")
def new_feature(data: FeatureRequest):
result = process_feature(data)
return result
# ✅ Zenable enforces feature flag requirement
@app.post("/new-feature")
@feature_flag("new_feature_enabled", rollout_percentage=10)
def new_feature(data: FeatureRequest, user: User = Depends(get_current_user)):
if not feature_flags.is_enabled("new_feature_enabled", user):
return {"error": "Feature not available"}
result = process_feature(data)
analytics.track("new_feature_used", user.id, result)
return result
```
### Example: Domain-Driven Design
**Your Policy:** "All business logic must be in domain services, not controllers"
```javascript expandable theme={null}
// ❌ AI puts logic in controller
app.post('/orders', async (req, res) => {
const order = req.body;
const total = order.items.reduce((sum, item) => sum + item.price, 0);
const tax = total * 0.08;
const finalAmount = total + tax;
// Business logic mixed with controller
db.save({...order, total: finalAmount});
res.json({success: true});
});
// ✅ Zenable enforces DDD separation
app.post('/orders', async (req, res) => {
const orderCommand = CreateOrderCommand.from(req.body);
const result = await orderService.createOrder(orderCommand);
res.json(OrderResponse.from(result));
});
// Business logic in domain service
class OrderService {
async createOrder(command) {
const order = Order.create(command);
order.calculateTotals(this.taxService);
await this.repository.save(order);
await this.eventBus.publish(new OrderCreatedEvent(order));
return order;
}
}
```
### Example: Analytics Pipeline Integration
**Your Policy:** "All user actions must emit structured analytics events"
```python expandable theme={null}
# ❌ AI generates without analytics
def update_profile(user_id, profile_data):
user = get_user(user_id)
user.update(profile_data)
save_user(user)
return {"success": True}
# ✅ Zenable adds analytics requirements
def update_profile(user_id, profile_data, request_context):
user = get_user(user_id)
old_profile = user.profile.copy()
# Track what changed
changes = diff_profiles(old_profile, profile_data)
user.update(profile_data)
save_user(user)
# Emit structured analytics event
analytics.track({
"event": "profile_updated",
"user_id": user_id,
"changes": changes,
"source": request_context.source,
"session_id": request_context.session_id,
"timestamp": datetime.now()
})
return {"success": True}
```
## Benefits
* **10x Development Speed** - Build features faster without technical debt
* **Consistent Architecture** - Enforce your patterns across all AI-generated code
* **Reduced Review Cycles** - Catch issues before PR submission
* **Team Knowledge Scaling** - Embed best practices into the development process
## Related Use Cases
* [Preventing AI Mistakes](/use-cases/preventing-ai-mistakes) - Catch AI errors in real-time
* [Policy as Code](/use-cases/policy-as-code) - Define your feature requirements
* [Starting New Projects](/use-cases/starting-new-project) - Begin with best practices
# Code Assessment
Source: https://docs.zenable.io/use-cases/code-assessment
Automated deep-dive analysis maps dependencies, identifies risks, and creates implementation roadmaps
## Overview
Understanding an existing codebase -- for an audit, due diligence, a modernization push, or a system you inherited -- traditionally requires months of manual analysis. Zenable provides automated deep-dive analysis that maps dependencies, identifies risks, and creates implementation roadmaps - giving you complete understanding of your code in hours, not months.
**The Zenable Assessment skill is coming soon.** A guided, interview-driven assessment for your coding agent: it helps you co-author custom requirements, runs a two-pass scan (deterministic checks plus an AI review against the same requirements), and produces a polished, evidence-backed report you can upload and share in the Zenable app -- while bootstrapping your tenant with the requirements, scopes, and guardrails you defined along the way.
Email [hello@zenable.io](mailto:hello@zenable.io) to get early access.
## Out-of-the-Box Analysis
Zenable automatically detects these code issues:
* **Code Smells** - Deep nesting, long methods, duplicate code
* **Outdated Patterns** - Deprecated APIs, obsolete libraries
* **Security Vulnerabilities** - SQL injection, hardcoded secrets, weak crypto
* **Technical Debt** - Missing tests, poor documentation, cyclomatic complexity
* **Dead Code** - Unused functions, unreachable code
* **Performance Issues** - N+1 queries, inefficient algorithms
## Custom Organization Requirements
Apply your specific modernization criteria:
> "All of our services must be migrated to our new microservices architecture, use our internal authentication service, follow our naming conventions, and include telemetry with our monitoring stack."
## In Action
```bash theme={null}
# Run a comprehensive assessment, including custom requirements
zenable check '**/*'
```
## Custom Modernization Examples
### Example: Microservices Migration
**Your Policy:** "All monolithic components must be refactored into domain-bounded microservices"
```python expandable theme={null}
# ❌ Existing monolith
class UserService:
def create_user(self, data):
user = self.validate_user(data)
self.send_email(user.email) # Mixing concerns
self.update_inventory(user) # Unrelated domain
self.log_analytics(user) # Another concern
return user
# ✅ Zenable suggests microservices refactor
class UserService:
def create_user(self, data):
user = self.validate_user(data)
event_bus.publish("user.created", user)
return user
# Separate services handle their domains
# EmailService, InventoryService, AnalyticsService
```
### Example: Internal Standards Migration
**Your Policy:** "Replace all direct database calls with our DataAccess layer"
```javascript theme={null}
// ❌ Direct DB access
function getUser(id) {
const result = db.query(`SELECT * FROM users WHERE id = ${id}`);
return result[0];
}
// ✅ Zenable enforces your data layer
function getUser(id) {
return DataAccess.users.findById(id, {
cache: true,
metrics: true,
audit: true
});
}
```
### Example: Tech Stack Modernization
**Your Policy:** "Migrate from jQuery to React, replace callback patterns with async/await"
```javascript expandable theme={null}
// ❌ Aging jQuery code
$(document).ready(function() {
$.ajax({
url: '/api/data',
success: function(data) {
$('#result').html(data);
}
});
});
// ✅ Zenable suggests modern React
import { useState, useEffect } from 'react';
function DataComponent() {
const [data, setData] = useState(null);
useEffect(() => {
const fetchData = async () => {
const response = await fetch('/api/data');
setData(await response.json());
};
fetchData();
}, []);
return
{data}
;
}
```
### Example: Observability Requirements
**Your Policy:** "All services must add distributed tracing and structured logging"
```python expandable theme={null}
# ❌ No observability
def process_payment(amount):
result = payment_gateway.charge(amount)
return result
# ✅ Zenable adds your observability
from opentelemetry import trace
from structlog import get_logger
tracer = trace.get_tracer(__name__)
logger = get_logger()
def process_payment(amount):
with tracer.start_as_current_span("process_payment") as span:
span.set_attribute("payment.amount", amount)
logger.info("payment.started", amount=amount)
result = payment_gateway.charge(amount)
logger.info("payment.completed",
amount=amount,
transaction_id=result.id)
return result
```
## Benefits
* **Complete Tech Debt Understanding** - Know exactly what needs modernization
* **Custom Migration Path** - Enforce your specific architectural standards
* **Risk-Based Prioritization** - Focus on critical issues first
* **Accelerated Modernization** - Move from months to hours of analysis
## Related Use Cases
* [Security Assessment](/use-cases/security-assessment) - Deep security analysis
* [Policy as Code](/use-cases/policy-as-code) - Prevent future technical debt
* [Starting New Projects](/use-cases/starting-new-project) - Build with modern standards
# Compliance Pre-Audit
Source: https://docs.zenable.io/use-cases/compliance-pre-audit
Upload your framework (SOC 2, HIPAA, FedRAMP, etc.) and governance to get continuous compliance monitoring directly in your SDLC
## Overview
Audit preparation is stressful, manual, and reveals surprises at the worst time. Upload your framework (SOC 2, HIPAA, FedRAMP, etc.) and governance to get continuous compliance monitoring directly in your SDLC, enabling you to pass audits on the first attempt with zero surprises.
## How It Works
1. **Upload Your Framework** - Any compliance document, audit checklist, or regulatory requirement at [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=compliance-pre-audit\&utm_content=upload-framework)
2. **Automatic Extraction** - We identify and structure all technical requirements
3. **Continuous Enforcement** - Every developer action is checked against your requirements
4. **Evidence Generation** - Generate custom compliance reports using our MCP server
## Universal Framework Support
Zenable is a flexible multi-purpose tool that supports any requirements, including any and all compliance frameworks:
• SOC 2 Trust Services Criteria
• HIPAA Technical Safeguards
• FedRAMP Security Controls
• ISO 27001 Annex A Controls
• GDPR Data Protection Requirements
• PCI DSS Requirements
• Your internal security policies
• Customer contractual requirements
• Industry-specific regulations
• Vendor assessment criteria
• M\&A due diligence standards
• Partner integration requirements
## Real-World Example: Custom Security Policy
Imagine uploading your organization's security policy that states:
> "All API endpoints must implement rate limiting of no more than 100 requests per minute per user, use OAuth 2.0 authentication, and log all access attempts with user ID, timestamp, and IP address."
### What Zenable Prevents
With this requirement uploaded, Zenable would automatically:
```python theme={null}
# ❌ Would be flagged
@app.route('/api/users')
def get_users():
return jsonify(users)
# ✅ Zenable ensures
@app.route('/api/users')
@rate_limit(100, per=60) # 100 requests per minute
def get_users():
return jsonify(users)
```
```python theme={null}
# ❌ Would be flagged
@app.route('/api/data')
def get_data():
return sensitive_data
# ✅ Zenable ensures
@app.route('/api/data')
@require_oauth2
def get_data():
return sensitive_data
```
```python theme={null}
# ❌ Would be flagged
def process_request(request):
return handle(request)
# ✅ Zenable ensures
def process_request(request):
log_access(
user_id=request.user.id,
timestamp=datetime.now(),
ip_address=request.remote_addr
)
return handle(request)
```
## Running Compliance Checks
### Unified Assessment
After uploading your compliance frameworks to [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=compliance-pre-audit\&utm_content=configure-frameworks), run a single unified check across all frameworks:
```bash theme={null}
# Check against all uploaded frameworks at once
zenable check '**/*'
```
This single command checks your codebase against:
* All uploaded compliance frameworks (SOC 2, HIPAA, FedRAMP, etc.)
* Your custom organizational policies
* Industry-specific regulations
* Contractual requirements
The results show compliance status across all frameworks simultaneously.
## Framework-Specific Examples
### HIPAA Technical Safeguards
Upload your HIPAA requirements document, and Zenable ensures:
**Requirement**: "Implement procedures to verify that a person seeking access to ePHI is authorized (§164.312(d))"
**What Gets Prevented**:
* Direct database queries without access checks
* Missing authentication on health data endpoints
* Unencrypted storage of patient information
* Missing audit logs for PHI access
### FedRAMP Security Controls
Upload FedRAMP control requirements:
**Requirement**: "The information system enforces approved authorizations for logical access (AC-3)"
**What Gets Prevented**:
* Hardcoded credentials in source code
* Missing role-based access controls
* Unauthorized privilege escalation paths
* Unvalidated user input in security contexts
### GDPR Data Protection
Upload GDPR requirements:
**Requirement**: "Implement appropriate technical measures to ensure data protection by design (Article 25)"
**What Gets Prevented**:
* Missing data encryption at rest
* Lack of data deletion capabilities
* Absent consent management
* Uncontrolled data retention
## Evidence Generation with MCP Server
### Setting Up for Compliance Reports
After configuring the MCP server ([setup guide](/integrations/mcp/getting-started)), you can use AI assistance to generate comprehensive compliance evidence:
```bash theme={null}
# Install and configure MCP server
zenable install
```
Use your AI assistant (Claude, Cursor, Antigravity, etc.) with prompts like:
**Example prompt for SOC 2 evidence:**
> "Generate a SOC 2 compliance report by checking all authentication, encryption, and logging implementations. For each file, send it to Zenable for analysis and compile the results into a summary showing: control objectives met, gaps identified, and remediation recommendations."
**Example prompt for multi-framework assessment:**
> "Create a comprehensive compliance assessment covering SOC 2, GDPR, and our internal security policies. Check each module in our codebase against these frameworks using Zenable, then produce an executive summary with compliance percentages, critical findings, and a prioritized remediation plan."
**Example prompt for audit preparation:**
> "Prepare evidence for our upcoming HIPAA audit. Analyze all patient data handling code, encryption implementations, and access controls using Zenable. Generate a detailed report mapping each finding to specific HIPAA requirements with supporting code references."
The AI assistant will:
* Send each relevant file to Zenable for analysis
* Map findings to specific compliance requirements
* Generate formatted reports with code references
* Create audit-ready documentation
### Continuous Compliance Monitoring
Zenable provides automatic compliance monitoring at every stage:
**Real-Time Enforcement**
* **MCP Integration** - Every file edit in your IDE is checked instantly
* **PR Review Bot** - Automatic review on every pull request
* **Unified Checks** - Single command validates against all frameworks
No manual workflow setup required - just install the GitHub App and MCP server to get started.
## Benefits
### For Development Teams
* **Compliance Made Simple** - Requirements automatically translated into actionable code feedback
* **Fix Issues Early** - Catch compliance gaps in the IDE, not during audit season
* **Focus on Features** - Let Zenable handle compliance complexity while you build
### For Compliance Teams
* **Continuous Monitoring** - Real-time visibility into compliance posture across all code
* **Automated Evidence Collection** - Every code change tracked and mapped to requirements
* **Proactive Risk Management** - Identify and address gaps before they become findings
### For Auditors
* **Complete Audit Trail** - Every requirement traced from policy to implementation
* **Real-Time Evidence** - Current compliance status, not point-in-time snapshots
* **Simplified Review Process** - Pre-organized evidence mapped to control objectives
## Getting Started
Visit [zenable.app](https://www.zenable.app?utm_source=docs\&utm_medium=compliance-pre-audit\&utm_content=get-started) to upload your compliance documents
Install automated PR reviews in two clicks at [zenable.io/github](https://zenable.io/github?utm_source=docs\&utm_medium=compliance-pre-audit\&utm_content=github-install)
```bash theme={null}
zenable install
```
Seriously, that's it. You're all set.
Your requirements are now enforced automatically across all development
## Next Steps
* [Set up GitHub integration](/integrations/vcs-reviewers/github) or [GitLab integration](/integrations/vcs-reviewers/gitlab) for PR/MR-level enforcement
* Implement [Policy as Code](/use-cases/policy-as-code) for custom controls
* Configure [Security Assessment](/use-cases/security-assessment) for deeper analysis
# Finding & Fixing Bugs
Source: https://docs.zenable.io/use-cases/finding-fixing-bugs
AI-powered analysis identifies subtle bugs and suggests fixes before production
## Overview
Bugs slip through reviews and automated testing misses edge cases. Zenable provides AI-powered analysis that identifies subtle bugs and suggests fixes before production, resulting in fewer production incidents.
## Out-of-the-Box Bug Detection
Zenable automatically identifies these common bug patterns:
* **Race Conditions** - Unsafe concurrent access, thread safety issues
* **Null/Undefined** - Missing null checks, potential NPEs
* **Resource Leaks** - Unclosed files, database connections, memory leaks
* **Logic Errors** - Off-by-one errors, incorrect conditionals
* **Type Mismatches** - Implicit conversions, type confusion
* **Edge Cases** - Boundary conditions, empty collections
## Custom Bug Detection Rules
Define your organization's specific bug patterns:
> "All database operations must use our retry wrapper, all API calls must include correlation IDs, all monetary calculations must use our Money class with 4 decimal precision, and all user inputs must be sanitized with our custom sanitizer."
## In Action
```bash theme={null}
# Comprehensive bug scan with both standard and custom checks
zenable check '**/*.{py,js,ts,go}'
# Focus on critical code paths, excluding test files
zenable check 'src/api/**/*' 'src/payments/**/*' \
--exclude '**/test_*.py' \
--exclude '**/*.test.{js,ts}' \
--exclude '**/*_test.go'
```
## Custom Bug Examples
### Example: Business Logic Validation
**Your Policy:** "All financial calculations must account for currency conversion and rounding rules"
```python expandable theme={null}
# ❌ Common bug: incorrect money handling
def calculate_total(items):
return sum(item.price for item in items)
# ✅ Zenable enforces your money handling rules
def calculate_total(items):
total = Money(0, currency="USD")
for item in items:
converted = currency_service.convert(
item.price,
from_currency=item.currency,
to_currency="USD",
rate_date=datetime.now()
)
total = total.add(converted, rounding=ROUND_HALF_EVEN)
return total
```
### Example: API Contract Enforcement
**Your Policy:** "All API responses must include request ID, timestamp, and rate limit headers"
```javascript expandable theme={null}
// ❌ Missing required response structure
app.get('/api/users', async (req, res) => {
const users = await db.getUsers();
res.json(users);
});
// ✅ Zenable enforces API contract
app.get('/api/users', async (req, res) => {
const users = await db.getUsers();
res.set({
'X-Request-ID': req.id,
'X-Timestamp': Date.now(),
'X-RateLimit-Remaining': req.rateLimit.remaining
});
res.json({
data: users,
meta: {
request_id: req.id,
timestamp: Date.now(),
count: users.length
}
});
});
```
### Example: Data Consistency Rules
**Your Policy:** "All database writes must use transactions with retry logic and audit logging"
```python expandable theme={null}
# ❌ Bug: no transaction or retry
def update_user_balance(user_id, amount):
user = get_user(user_id)
user.balance += amount
save_user(user)
# ✅ Zenable enforces consistency requirements
@with_retry(max_attempts=3, backoff=exponential)
@with_transaction
@audit_log
def update_user_balance(user_id, amount, reason):
with db.transaction() as tx:
user = tx.query(User).with_for_update().get(user_id)
old_balance = user.balance
user.balance += amount
tx.add(BalanceHistory(
user_id=user_id,
old_balance=old_balance,
new_balance=user.balance,
change_amount=amount,
reason=reason
))
tx.commit()
```
## Benefits
* **Fewer Production Incidents** - Catch bugs before they reach users
* **Custom Rule Enforcement** - Ensure your specific patterns are followed
* **Reduced Debugging Time** - Find root causes faster
* **Improved Code Quality** - Systematic bug prevention
## Related Use Cases
* [Preventing AI Mistakes](/use-cases/preventing-ai-mistakes) - Stop bugs at the source
* [Security Assessment](/use-cases/security-assessment) - Deep vulnerability analysis
* [Policy as Code](/use-cases/policy-as-code) - Define bug prevention rules
# Policy as Code
Source: https://docs.zenable.io/use-cases/policy-as-code
Automatic conversion of policies to executable rules with version control and testing
## Overview
Translating governance policies into enforceable technical controls is error-prone. Zenable provides automatic conversion of policies to executable rules with version control and testing, ensuring 100% policy enforcement with full traceability.
## How Zenable Works
Upload your policy documents once, and Zenable automatically:
1. **Extracts** technical requirements from natural language
2. **Converts** them into enforceable rules
3. **Applies** them across every line of code
## Creating Policies as Code
Go to [zenable.app/requirements](https://www.zenable.app/requirements?utm_source=docs\&utm_medium=policy-as-code\&utm_content=requirements) to:
* Upload a policy document, or
* Create a requirement directly
Visit [zenable.app/guardrails](https://www.zenable.app/guardrails?utm_source=docs\&utm_medium=policy-as-code\&utm_content=guardrails) to see your requirements translated into executable guardrails
Your policies are now automatically enforced across all development - no additional configuration needed
## Real-World Policy Example
Imagine uploading a policy document that states:
> "All payment processing code must use encrypted channels, implement idempotency keys, log all transactions with correlation IDs, and retry failed transactions with exponential backoff."
### What Zenable Prevents
With this policy uploaded, Zenable automatically enforces:
```python theme={null}
# ❌ Would be flagged
def process_payment(amount, card):
response = requests.post(
"http://api.example.com/charge", # Unencrypted!
json={"amount": amount, "card": card}
)
# ✅ Zenable ensures
def process_payment(amount, card):
response = requests.post(
"https://api.example.com/charge", # Encrypted
json={"amount": amount, "card": card}
)
```
```python theme={null}
# ❌ Would be flagged
def charge_customer(customer_id, amount):
return payment_gateway.charge(customer_id, amount)
# ✅ Zenable ensures
def charge_customer(customer_id, amount, idempotency_key=None):
if not idempotency_key:
idempotency_key = generate_idempotency_key()
return payment_gateway.charge(
customer_id, amount,
idempotency_key=idempotency_key
)
```
## Policy Definition
### Creating Custom Policies
Simply upload your policy documents to Zenable, and we automatically convert them into enforceable rules applied through CLI and IDE integrations.
#### Example: Security Policy
```yaml expandable theme={null}
# security-policy.yaml (conceptual - configured in Zenable platform)
rules:
- id: hardcoded-api-key
patterns:
- pattern-either:
- pattern: $KEY = "..."
- pattern: $KEY = '...'
- metavariable-regex:
metavariable: $KEY
regex: (?i).*(api_key|apikey|api-key|secret_key|secret-key)
message: |
Hardcoded API key detected. This is a security risk.
Store API keys in environment variables or secure key management systems.
languages: [python, javascript, java]
severity: ERROR
metadata:
category: security
cwe: CWE-798
owasp: A3
- id: sql-injection-string-concat
patterns:
- pattern-either:
- pattern: |
$QUERY = "..." + $INPUT + "..."
...
$CURSOR.execute($QUERY, ...)
- pattern: |
$QUERY = f"... {$INPUT} ..."
...
$CURSOR.execute($QUERY, ...)
- pattern: |
$QUERY = "...".format($INPUT)
...
$CURSOR.execute($QUERY, ...)
message: |
SQL query constructed using string concatenation with user input.
This can lead to SQL injection vulnerabilities.
Use parameterized queries instead.
languages: [python]
severity: ERROR
metadata:
category: security
cwe: CWE-89
owasp: A1
- id: missing-authentication-decorator
patterns:
- pattern: |
@app.route(...)
def $FUNC(...):
...
- pattern-not: |
@app.route(...)
@require_auth
def $FUNC(...):
...
- metavariable-regex:
metavariable: $FUNC
regex: .*(admin|user|account|profile|settings).*
message: |
Sensitive endpoint detected without authentication decorator.
Add @require_auth to protect this endpoint.
languages: [python]
severity: WARNING
metadata:
category: security
cwe: CWE-306
```
#### Example: Code Quality Policy
```yaml expandable theme={null}
# quality-policy.yaml (conceptual - configured in Zenable platform)
rules:
- id: no-empty-exception-handlers
patterns:
- pattern: |
try:
...
except $EXCEPTION:
pass
message: |
Empty exception handler detected. This can hide errors and make debugging difficult.
At minimum, log the exception or add a comment explaining why it's being ignored.
languages: [python]
severity: WARNING
metadata:
category: best-practice
- id: no-console-log-production
patterns:
- pattern-either:
- pattern: console.log(...)
- pattern: console.debug(...)
- pattern: console.info(...)
message: |
Console logging detected. Remove or replace with proper logging before production.
languages: [javascript, typescript]
severity: INFO
metadata:
category: best-practice
- id: missing-error-handling
patterns:
- pattern: |
$PROMISE = $ASYNC_FUNC(...)
- pattern-not: |
$PROMISE = $ASYNC_FUNC(...).catch(...)
- pattern-not: |
try {
...
$PROMISE = await $ASYNC_FUNC(...)
...
} catch (...) {
...
}
message: |
Async operation without error handling. Add .catch() or try/catch block.
languages: [javascript, typescript]
severity: WARNING
metadata:
category: error-handling
```
## Policy Enforcement Strategies
### Development-Time Enforcement
With Zenable MCP installed, policies are enforced as developers write code:
```bash theme={null}
zenable install
```
The AI assistant will automatically:
* Check code against policies
* Suggest corrections
* Apply fixes
Enforce policies before code is committed:
```yaml theme={null}
# .pre-commit-config.yaml
---
repos:
- repo: https://github.com/Zenable-io/skills
rev: v3.0.0 # Consider `pre-commit autoupdate --freeze` to safely lock and maintain this
hooks:
- id: zenable-check
```
Install the [GitHub App](https://zenable.io/github?utm_source=docs\&utm_medium=policy-as-code\&utm_content=github-install) for automatic PR reviews. Once installed, every pull request is automatically reviewed against your policies.
## Next Steps
* Review our [Deployment & Adoption Guide](/deployment-adoption) for best practices
* Set up [Supply Chain Security](/use-cases/supply-chain-security) policies
* Configure [AI Tools Integration](/use-cases/ai-tools-new-features) with policies
* Implement [Compliance Assessment](/use-cases/compliance-pre-audit) based on policies
# Preventing AI Mistakes
Source: https://docs.zenable.io/use-cases/preventing-ai-mistakes
Real-time safety net that catches SQL injections, hardcoded secrets, and policy violations as code is written
## Overview
AI coding assistants generate vulnerable code with security flaws and compliance violations. Zenable acts as a real-time safety net that catches SQL injections, hardcoded secrets, and policy violations as code is written - ensuring you ship AI-accelerated code with confidence and zero security compromises.
## How It Works
Zenable provides two layers of protection:
1. **Out-of-the-Box Protection** - Industry-standard security and quality checks that apply to everyone
2. **Custom Requirements** - Your organization's unique policies and decisions
## Out-of-the-Box Protection
Zenable automatically prevents common AI mistakes without any configuration:
* **SQL Injection** - Enforces parameterized queries
* **Hardcoded Secrets** - Detects API keys, passwords, tokens
* **XSS Vulnerabilities** - Prevents script injection attacks
* **Path Traversal** - Blocks directory traversal attempts
* **Missing Authentication** - Flags unprotected endpoints
* **Weak Cryptography** - Identifies insecure algorithms
* **Resource Leaks** - Ensures proper cleanup (files, connections)
* **Error Handling** - Requires try-catch for critical operations
* **Type Safety** - Enforces proper typing in TypeScript/Python
* **Performance Issues** - Catches N+1 queries, inefficient loops
* **Race Conditions** - Identifies thread safety issues
### Quick Example: Standard Protections
```python theme={null}
# ❌ AI generates (multiple standard violations)
def get_user_data(user_id):
conn = db.connect() # Resource leak
query = f"SELECT * FROM users WHERE id = {user_id}" # SQL injection
return conn.execute(query)
# ✅ Zenable automatically fixes
def get_user_data(user_id):
with db.connect() as conn: # Proper resource management
query = "SELECT * FROM users WHERE id = ?" # Parameterized query
return conn.execute(query, (user_id,))
```
## Custom Organization Requirements
Upload your unique organizational decisions and policies for enforcement:
> "Our payment processing must always use our internal PaymentOrchestrator service, never direct gateway calls. All customer data operations must include audit logging with department tags. Use our custom retry policy: 3 attempts with exponential backoff starting at 2 seconds."
### Real Custom Requirements Examples
#### Example 1: Internal Service Architecture
**Your Policy:** "All external API calls must go through our API Gateway service with circuit breakers"
```python theme={null}
# ❌ AI might generate direct calls
async def fetch_weather(city):
response = await requests.get(f"https://api.weather.com/v1/{city}")
return response.json()
# ✅ Zenable enforces your architecture
async def fetch_weather(city):
return await api_gateway.call(
service="weather",
endpoint=f"/v1/{city}",
circuit_breaker=True,
timeout=5000
)
```
#### Example 2: Company-Specific Audit Requirements
**Your Policy:** "All data modifications must log: user ID, department, cost center, and business justification"
```python expandable theme={null}
# ❌ AI generates standard CRUD
def update_inventory(product_id, quantity):
db.execute("UPDATE inventory SET quantity = ? WHERE id = ?",
(quantity, product_id))
# ✅ Zenable adds your audit requirements
def update_inventory(product_id, quantity, user_context):
audit_log.record({
"action": "inventory_update",
"user_id": user_context.id,
"department": user_context.department,
"cost_center": user_context.cost_center,
"justification": user_context.business_reason,
"changes": {"product_id": product_id, "new_quantity": quantity}
})
db.execute("UPDATE inventory SET quantity = ? WHERE id = ?",
(quantity, product_id))
```
#### Example 3: Custom Business Logic
**Your Policy:** "All pricing calculations must include our dynamic margin algorithm based on customer tier and seasonality"
```javascript expandable theme={null}
// ❌ AI uses simple calculation
function calculatePrice(basePrice, discount) {
return basePrice * (1 - discount);
}
// ✅ Zenable enforces your business rules
function calculatePrice(basePrice, customerId) {
const customer = getCustomer(customerId);
const seasonalFactor = getSeasonalPricingFactor();
const tierMultiplier = getTierMultiplier(customer.tier);
const dynamicMargin = calculateDynamicMargin(
customer.purchaseHistory,
seasonalFactor
);
return basePrice * tierMultiplier * seasonalFactor * (1 + dynamicMargin);
}
```
#### Example 4: Compliance-Driven Requirements
**Your Policy:** "European customer data must stay in EU regions and use GDPR-compliant deletion"
```python expandable theme={null}
# ❌ AI doesn't consider data residency
def delete_user(user_id):
db.execute("DELETE FROM users WHERE id = ?", (user_id,))
# ✅ Zenable enforces compliance requirements
def delete_user(user_id):
user = get_user(user_id)
if user.region == "EU":
# GDPR-compliant soft delete with retention policy
eu_db.execute(
"UPDATE users SET deleted_at = ?, anonymized = true WHERE id = ?",
(datetime.now(), user_id)
)
schedule_permanent_deletion(user_id, days=30)
notify_data_protection_officer(user_id, "soft_delete")
else:
# Standard deletion for non-EU
db.execute("DELETE FROM users WHERE id = ?", (user_id,))
```
## In Action
When you use AI to generate code, Zenable automatically:
1. Applies all standard security and quality checks
2. Enforces your custom organizational requirements
3. Provides immediate feedback to the AI for correction
4. Shows you the safe, conformant version
## Why Custom Requirements Matter
### Enforce Architectural Decisions
* Ensure AI respects your microservice boundaries
* Maintain consistent use of internal libraries
* Enforce your specific design patterns
### Maintain Business Logic
* Protect proprietary algorithms
* Ensure regulatory compliance
* Enforce customer-specific requirements
### Preserve Team Standards
* Maintain your naming conventions
* Enforce your logging standards
* Keep your error handling patterns
## Related Use Cases
* [AI Tools & New Features](/use-cases/ai-tools-new-features) - Build features faster
* [Policy as Code](/use-cases/policy-as-code) - Define custom rules programmatically
* [Security Assessment](/use-cases/security-assessment) - Deep security scanning
# Security Assessment
Source: https://docs.zenable.io/use-cases/security-assessment
Continuous security scanning with context-aware vulnerability detection and remediation
## Overview
Security vulnerabilities hide in complex codebases and evolve with new threats. Zenable provides continuous security scanning with context-aware vulnerability detection and remediation, delivering a proactive security posture with significant reduction in vulnerabilities reaching production.
## Out-of-the-Box Protection
Zenable automatically detects these security vulnerabilities:
* **OWASP Top 10** - SQL injection, XSS, broken auth, etc.
* **Cryptographic Weaknesses** - Weak algorithms, poor randomness
* **Hardcoded Secrets** - API keys, passwords, tokens
* **Injection Attacks** - Command, LDAP, XML injection
* **Insecure Deserialization** - Unsafe object handling
* **Known CVEs** - Checks against vulnerability databases
## Custom Security Requirements
Enforce your organization's specific security policies:
> "All financial transactions must use our SecurePayment service with dual-approval workflow, all PII must be encrypted with AES-256-GCM, and all external APIs must use mTLS with certificate pinning."
## In Action
```bash theme={null}
# Run comprehensive security scan with both standard and custom checks
zenable check '**/*.{py,js,ts,go,java}'
```
## Custom Security Examples
### Example: Financial Services Requirements
**Your Policy:** "All payment processing must use tokenization and include fraud detection scoring"
```python theme={null}
# ❌ AI/developer might write
def process_payment(card_number, amount):
charge_card(card_number, amount)
return "success"
# ✅ Zenable enforces your requirements
def process_payment(payment_token, amount, user_context):
fraud_score = fraud_detection.analyze(user_context, amount)
if fraud_score > 0.7:
security_team.alert(user_context, fraud_score)
return "requires_review"
result = tokenized_payment.process(payment_token, amount)
audit_log.record_payment(result, fraud_score)
return result
```
### Example: Healthcare Data Protection
**Your Policy:** "All PHI must be encrypted at field level with key rotation every 30 days"
```python theme={null}
# ❌ Standard encryption
def store_patient_data(patient_data):
encrypted = encrypt(json.dumps(patient_data))
db.save(encrypted)
# ✅ Zenable enforces field-level encryption
def store_patient_data(patient_data):
encrypted_fields = {}
for field, value in patient_data.items():
if field in PHI_FIELDS:
key = key_manager.get_current_key(field)
encrypted_fields[field] = field_encrypt(value, key)
else:
encrypted_fields[field] = value
db.save(encrypted_fields)
key_manager.schedule_rotation()
```
### Example: Zero Trust Architecture
**Your Policy:** "All internal service calls must use mutual TLS with service mesh integration"
```python theme={null}
# ❌ Direct service calls
def get_user_profile(user_id):
response = requests.get(f"http://user-service/users/{user_id}")
return response.json()
# ✅ Zenable enforces zero trust
def get_user_profile(user_id):
response = service_mesh.call(
service="user-service",
endpoint=f"/users/{user_id}",
mtls_cert=get_service_certificate(),
verify_peer=True,
timeout=5000
)
return response.json()
```
## Benefits
* **Proactive Security Posture** - Find vulnerabilities before attackers do
* **Custom Policy Enforcement** - Ensure your specific security requirements are met
* **Reduced Security Debt** - Prevent vulnerabilities from accumulating
* **Compliance Ready** - Meet regulatory security requirements
## Related Use Cases
* [Preventing AI Mistakes](/use-cases/preventing-ai-mistakes) - Stop vulnerabilities at the source
* [Policy as Code](/use-cases/policy-as-code) - Define security policies programmatically
* [Supply Chain Security](/use-cases/supply-chain-security) - Secure your dependencies
# Starting New Projects
Source: https://docs.zenable.io/use-cases/starting-new-project
Automated project scaffolding with built-in governance, security, and compliance
## Overview
New projects start without proper governance setup, creating technical debt from day one. Zenable provides automated project scaffolding with built-in governance, security, and compliance - ensuring projects start right with zero governance debt.
## AI-Native Python Template
The [AI-Native Python](https://github.com/Zenable-io/ai-native-python?utm_source=docs\&utm_medium=starting-new-project\&utm_content=cookiecutter) is a cookiecutter template that provides a production-ready Python project with built-in governance, automated quality checks, and AI-optimized development.
### Quick Start
Install the package manager from [brew.sh](https://brew.sh/)
```bash theme={null}
# Install uv package manager (if not already installed)
which uvx || brew install uv
# Create new project from template
uvx --with gitpython cookiecutter gh:zenable-io/ai-native-python
```
You'll be prompted for configuration options such as:
* Project name and description
* Organization details
* GitHub settings
* Technical preferences (Python version, Docker support, etc.)
```bash theme={null}
# Navigate to your new project
cd your-project-name
# Initialize the project
task init
# Start coding with AI assistance
claude # or your favourite IDE
```
**Zenable MCP Included!** The project generator automatically installs and configures the Zenable MCP server in your project, so AI assistants will immediately start enforcing your governance policies - no additional setup required.
## What's Included
The AI-Native Python template provides a complete, production-ready foundation with everything configured:
### Key Features
* **Modern Python Development** - Uses `uv` for lightning-fast dependency management
* **100% Test Coverage** - Enforced automatically, not aspirational
* **Security First** - Vulnerability scanning and SBOM generation built-in
* **Automated Everything** - Releases, versioning, and changelog generation
* **AI-Optimized** - Works seamlessly with Copilot, Cursor, Claude, and Antigravity
* **Docker Ready** - Multi-platform builds with optimized image sizes
* **Simple Yet Powerful** - One-command local setup, testing, deployment, and more
**Zenable Included by Default** - The template comes with Zenable pre-configured. No additional setup needed - governance checks and policy enforcement work automatically from your first commit.
### Key Benefits
* 5-minute project setup
* Start coding immediately
* No configuration overhead
* Everything just works
* 100% test coverage enforced
* Type safety guaranteed
* Security scanning automated
* Code quality checks on every commit
* Works with Copilot, Cursor, Claude
* Governance checks on AI suggestions
* Consistent patterns for AI to follow
* Reduced AI-generated bugs
* CI/CD fully configured
* Docker builds automated
* Semantic versioning
* Dependency updates managed
## Why Use AI-Native Python?
### The Traditional Way
* Spend hours setting up project structure
* Configure testing, linting, CI/CD manually
* Inconsistent practices across projects
* Security and compliance added as afterthoughts
* AI tools generate code that doesn't meet standards
### The AI-Native Way
* **5-minute setup** - Project ready with one command
* **Everything configured** - Testing, quality, CI/CD, security
* **Standardized approach** - Consistent across all projects
* **Built-in governance** - Security and compliance from day one
* **AI-optimized** - Tools generate conformant code automatically
## Next Steps
* Explore [AI Tools Integration](/use-cases/ai-tools-new-features) for development
* Set up [Policy as Code](/use-cases/policy-as-code) for your project
* Configure [Security Assessment](/use-cases/security-assessment) automation
# Supply Chain Security
Source: https://docs.zenable.io/use-cases/supply-chain-security
Monitor dependency changes, detect suspicious packages, prevent lookalike attacks, monitor for unwanted behavior / insider threats
## Overview
Dependencies change frequently and are nearly impossible to manage. Zenable monitors dependency changes, detects suspicious packages, prevents lookalike attacks, and monitors for unwanted behavior / insider threats - providing a protected supply chain and significant reduction in insider threat risk.
## Out-of-the-Box Protection
Zenable automatically provides these standard supply chain protections:
* **Typosquatting Detection** - Identifies lookalike package names
* **Known Vulnerabilities** - Checks against CVE databases
* **Suspicious Patterns** - Detects obfuscated code, unexpected network calls
* **License Compliance** - Flags incompatible licenses
* **Outdated Dependencies** - Identifies severely outdated packages
* **Malicious Package Detection** - Checks against known malware databases
## Custom Organization Requirements
Layer your specific supply chain policies on top:
> "All dependencies must be from our approved vendor list, no GPL licenses in production code, all packages must be internally mirrored, and any package from developers outside our organization requires security team approval."
### Example: Custom Vendor Requirements
**Your Policy:** "Only use packages from approved vendors with active support contracts"
```json theme={null}
// ❌ Zenable flags unapproved dependency
{
"dependencies": {
"random-utility": "^1.0.0", // Not from approved vendor
"community-lib": "^2.3.1" // No support contract
}
}
// ✅ Zenable ensures compliance
{
"dependencies": {
"@approved-vendor/utility": "^1.0.0",
"@enterprise/supported-lib": "^2.3.1"
}
}
```
### Example: Internal Registry Enforcement
**Your Policy:** "All packages must be pulled from our internal Artifactory mirror"
```bash theme={null}
# ❌ Standard npm install
npm install express
# ✅ Zenable enforces internal registry
npm install express --registry=https://artifactory.company.com/npm
```
## In Action
```bash theme={null}
# First, get a more useful summary of the uv.lock file
uv export --format requirements-txt --no-hashes > temp-requirements.txt
# Then, check your dependencies for both standard and custom violations
zenable check package.json temp-requirements.txt
# Cleanup
git checkout HEAD -- temp-requirements.txt 2>/dev/null || rm -f temp-requirements.txt
```
## Example Protection
### Lookalike Package Detection
```json theme={null}
// ❌ Zenable detects typosquatting
{
"dependencies": {
"expresss": "^4.17.1", // Extra 's' - likely typosquatting
"momnet": "^2.29.1" // 'momnet' instead of 'moment'
}
}
```
### Suspicious Behavior Detection
```python theme={null}
# ❌ Zenable flags unexpected behavior in dependencies
def innocent_function():
# Hidden data exfiltration attempt
import os
send_to_external(os.environ)
```
## Continuous Protection
Zenable continuously monitors your dependencies for:
* Changes in package behavior between versions
* New or modified dependencies in your codebase
* Suspicious patterns that could indicate compromise
* Lookalike packages that could be malicious
## Benefits
* **Protected Supply Chain** - Comprehensive monitoring of all code changes and usage of new dependencies
* **Reduced Insider Threat Risk** - Detect and prevent malicious updates from compromised developers
* **Prevent Lookalike Attacks** - Catch typosquatting and similar attacks before they cause damage
* **Monitor Unwanted Behavior** - Identify when dependencies start behaving suspiciously
## Real-World Custom Examples
### Financial Services Requirements
**Policy:** "All cryptographic libraries must be FIPS 140-2 validated"
### Healthcare Requirements
**Policy:** "No dependencies can transmit data to servers outside the US"
### Government Requirements
**Policy:** "All dependencies must be from US-based developers with security clearance"
## Related Use Cases
* [Security Assessment](/use-cases/security-assessment) - Identify vulnerabilities in your code
* [Policy as Code](/use-cases/policy-as-code) - Define dependency policies programmatically
* [Compliance Pre-Audit](/use-cases/compliance-pre-audit) - Ensure license compliance