Security Experience Decision Framework

01 Orientation Understand the five experience layers and how they relate before routing a feature decision.

How to use this document

Routing a new feature

Where does this belong?

Start with the workflow to identify which phase your feature lives in (Configure Scanners, Triage, Remediate, Govern). Then use the decision questions in that section to find the right layer.

Resolving a disagreement

We're debating two categories

Go to the Hard Cases section first — your case may already be addressed. If not, use the category cards to compare the categories being debated side-by-side.

Auditing an existing decision

Does this design match its category?

Use the Key Distinctions section to check that the feature's design aligns with its category's principles. Look for scope creep — features that bleed across boundaries.

When you're genuinely stuck: If a feature doesn't fit cleanly after using this framework, that's a signal the decision is non-trivial. Bring it to a Security PM/Design working session rather than resolving it unilaterally. Document the ruling here so the framework improves over time.

Category Reference

Scan Profiles

Use when the feature governs coverage

Defines which scanners run, where, and under what conditions. Governs inputs — not what happens to findings.

Platform-enforced Partial

Audit trail Partial

Auto-scales No

Policy / Gov

Use when the feature enforces a rule

Blocks, requires, or gates an outcome. Normative: defines what must or must not happen, consistently, across every project and team.

Platform-enforced Yes

Audit trail Yes

Auto-scales Yes

Agentic Orchestration

Use when the feature requires multi-step reasoning

Named, repeatable workflow combining context from multiple agents or sources that a single policy rule can't express.

Platform-enforced Yes

Audit trail Partial

Auto-scales Yes

One-off Duo Interactions

Use when the feature is a single AI interaction

One Duo prompt or interaction — not designed to scale or repeat. Chat interfaces, API access, single-turn agent use.

Platform-enforced No

Audit trail No

Auto-scales No

AI Configuration

Use when the feature shapes AI behavior platform-wide

Configures agentic data collectors that enrich policy signals but don't serve scanner coverage. Platform-wide infrastructure, not Security-specific.

Platform-enforced Yes

Audit trail Yes

Auto-scales Yes

How the categories relate

Platform-enforced User-initiated Rule-based Context-driven

Policy / Gov

AI Configuration

Agentic Orchestration

Scan Profiles

One-off Duo

Policies and Orchestration are both platform-enforced but differ on whether the outcome is predetermined (rule-based) or context-dependent. One-off Duo sits alone as the only user-initiated, non-repeatable category.

02 Decision Guide Use the decision questions in each phase to route your feature to the right experience layer.

Security Workflow Four sequential phases — click any phase to jump to its decision questions.

Phase 01 Configure Scanners

→

Phase 02 Triage

→

Phase 03 Remediate

→

Phase 04 Govern

AI Configuration and One-off Duo Interactions are cross-cutting — they appear within phases rather than as phases themselves.

Phase 01

Configure Scanners

Set up the scanners you need, where you need them. The core goal of scan configuration is coverage — defining which scanners run, on which projects and branches, and under what conditions. AI-based approaches to coverage (like AI SAST) belong here when they help users achieve coverage and require transparency into inputs and outputs. Agentic data collectors that don't serve coverage belong in a broader AI Configuration experience, outside of scan profiles.

Answer these questions to find the right layer for your feature:

Is this feature about what gets scanned — or what happens to findings?

Scan profiles define which scanners run, where, and under what conditions. They shouldn't define downstream behavior. If the feature touches what happens after a scan completes, it belongs in Policy or Orchestration.

Examples

Defining which scanners run, on which projects/branches, and on what schedule Because: Execution behavior is a scan profile concern — this is exactly what coverage configuration is for e.g. Enable SAST on all production branches, DAST on nightly

Scan Profiles

Configure AI SAST inputs — what context will be visible to the AI-based scanner Because: AI SAST requires transparency into its inputs to build user trust; this is still a coverage decision e.g. Which files, context signals, and scope the AI SAST will reason over

Scan Profiles

Defining what happens when a critical finding is detected Because: Scan profiles produce outputs; they shouldn't define what happens to them — downstream behavior lives in Policy e.g. Block merge, notify team, trigger remediation

Policy / Gov

Adding a "notify on critical finding" action directly to a scan profile Why not: Notification and remediation triggers are downstream enforcement — that's Policy, not scan configuration e.g. "Send Slack alert when critical finding detected" belongs in a scan execution policy, not the profile

Misrouted

Is this feature about scanner coverage — or agentic data collection?

Scan profiles are about coverage. AI-based tools belong in a profile only if they help users achieve coverage and require visible inputs and outputs. Agentic data collectors that enrich signals but don't serve coverage belong in a broader AI Configuration experience — not in scan profiles.

Examples

An AI-based approach to coverage (e.g. AI SAST) that requires transparent inputs and outputs Because: Coverage tools belong in scan profiles when they help users achieve coverage and need visible inputs/outputs e.g. AI SAST scanner with configurable context signals and scope settings

Scan Profiles

An agentic data collector that enriches policy signals but does not help users get coverage Because: Enriching signals is an AI Configuration concern — it doesn't help users understand or achieve scan coverage e.g. FP Agent that enriches findings with false-positive likelihood scores

AI Configuration

Define what an agent does with data it collects — triage, remediation, multi-step action Because: What agents do with data is orchestration — separate from what data they can access e.g. Agent that triages findings, filters FPs, then assigns to the right team

Agentic Orchestration

Configuring the FP Agent's data sources as part of scan profile setup Why not: Data collection agents that don't serve coverage belong in AI Configuration — mixing them into scan profiles blurs the boundary e.g. Configuring FP Agent inputs alongside SAST scanner settings in the same UI

Misrouted

Phase 02

Triage

Cut through the noise and act on what matters. Define how findings are evaluated and prioritized — through consistent enforcement rules, agent-enriched signals, or a combination of both.

Don't default to agents when a policy rule would be sufficient. If the outcome is consistent and rule-based, it belongs in Policy — agents add complexity and reduce auditability.

Answer these questions to find the right layer for your feature:

Are AI-enriched signals informing this triage decision?

The inputs that feed AI analyst triage decisions — FP analysis, SDLC context, agent-enriched signals — are configured and governed in a platform-wide AI Configuration experience, not in triage itself. Analysts can access this context in-workflow via a side panel, but the underlying configuration and governance of those inputs lives in AI Configuration and Agentic Orchestration.

Examples

Configure which inputs agents can ingest when evaluating a finding for triage Because: What agents can access is a platform-wide configuration concern — not owned by the triage workflow e.g. Allowing the FP Agent to ingest SDLC context and historical FP rates for a project

AI Configuration

Surface agent-enriched context to an analyst during triage via a side panel Because: This brings platform-wide AI context into the triage workflow without owning it — orchestration surfaces but doesn't govern the inputs e.g. Showing FP likelihood score and SDLC risk signals alongside a finding in the triage view

Agentic Orchestration

Define a rule that applies to all findings of a specific type once they're available Because: Consistent, single-condition rules with no agent reasoning belong in Policy — same finding type, same rule, every time e.g. Auto-dismiss all informational findings from dependency scanners on non-production branches

Policy / Gov

Building the FP Agent's data source configuration directly into the triage workflow settings Why not: Agent input configuration is a platform-wide AI Configuration concern — not owned by the triage workflow. Triage surfaces enriched signals; it doesn't govern where they come from e.g. A triage settings panel that controls which SDLC signals the FP Agent can access belongs in AI Configuration, not triage

Misrouted

Does this feature need to enforce a consistent rule across all findings of this type?

If yes, it's a policy. Policies define enforcement rules that apply uniformly — same finding type, same rule, every time, across any project or team. If the outcome depends on multi-signal reasoning or context that varies, it's orchestration.

Examples

Apply a consistent rule based on severity, CVE/EPSS, FP signals, or combined multi-signal inputs Because: Uniform rules on well-defined inputs are policy — same finding type, same rule, every time e.g. Flag all critical severity findings with EPSS > 0.7 for immediate review

Policy / Gov

Ask Duo to analyze patterns and suggest one or more improved policy rules (single prompt) Because: One-time, user-initiated — useful for exploration, not reproducible at scale e.g. "Duo, what rules would have caught most of our high-severity FPs last quarter?"

One-off Duo

Ongoing, multi-step pattern analysis that surfaces suggestions without a human prompt Because: Ongoing analysis without a human trigger is a named, repeatable workflow — not a one-off interaction e.g. Weekly agent that analyzes FP patterns across projects and surfaces policy recommendations

Agentic Orchestration

Combine signals from multiple agents before deciding what to do Because: Multi-agent reasoning that synthesizes different context sources can't be expressed as a single policy rule e.g. SDLC Agent + FP Agent + Code Quality Agent signals combined to score remediation priority

Agentic Orchestration

Using an orchestration flow to auto-close all low-severity findings Why not: A single-condition rule with a consistent output is a policy — orchestration here adds complexity and reduces auditability without any benefit e.g. "If severity = low → close" is a two-line policy rule, not a multi-step agent workflow

Misrouted

Does the triage decision require context from multiple sources or agents?

Single-source conditions belong in policy. When a meaningful triage decision requires collecting context across pipeline state, team ownership, branch activity, or multiple agent outputs — that's orchestration.

Examples

Triage based on a single scan output condition (severity, branch, scanner type) Because: Single-source conditions with a fixed outcome are policy — no multi-agent reasoning needed e.g. Flag all critical findings on main branch for immediate review

Policy / Gov

Triage after collecting context from SDLC Agent, code quality signals, and deployment risk Because: Cross-source context collection that synthesizes multiple signals to reach a conclusion requires orchestration e.g. Prioritize findings based on combined SDLC context, code churn, and deployment risk score

Agentic Orchestration

One-off triage exploration via Security Analyst chat Because: Single user-initiated interaction — useful for investigation, not designed to run at scale e.g. "Duo, why is this finding flagged as high priority given the deployment context?"

One-off Duo

Writing a policy rule to prioritize findings based on SDLC context, deployment risk, and FP confidence score Why not: A policy acts on a single, well-defined input condition — it can't collect and synthesize context from multiple agent sources before making a decision. Multi-signal reasoning requires orchestration e.g. "If SDLC risk = high AND FP score < 0.3 AND deployment imminent → escalate" requires three separate agent signals to be collected and reasoned over before the condition can be evaluated

Misrouted

Phase 03

Remediate

Drive consistent, auditable outcomes via enforcement rules or orchestration flows. When a pattern repeats, consider promoting it from flow to policy.

Don't put remediation behavior inside a scan profile — scan profiles produce outputs, they shouldn't define what happens next.

Answer these questions to find the right layer for your feature:

Does this outcome need to be consistent, traceable, and rule-based?

A policy is a Trigger + Rule + Action: same input → same output, every time. If your outcome fits this framework, it belongs in Policy — not orchestration. Policies also scale beyond Security: branch rules, merge requirements, and approval gates are all policy-layer constructs.

Examples

Block MR merge on non-default branches when a critical vulnerability is detected Because: A trigger + rule + action with a fixed, auditable outcome — this is exactly what policies are for e.g. Critical finding on production branch → merge blocked and team notified

Policy / Gov

Policy-triggered agent actions that are consistent, reproducible, and more auditable than ad hoc flows Because: When an agent action is triggered by a deterministic rule and always produces the same result, the trigger belongs in Policy e.g. Critical finding detected → policy triggers auto-assignment to remediation agent

Policy / Gov

Enforce compliance requirements, approval gates, audit logging, status transitions Because: Compliance enforcement requires the full audit trail and consistency guarantees that only Policy can provide e.g. Two security lead approvals required before any critical finding can be closed

Policy / Gov

Building an orchestration flow to block MRs on critical findings Why not: A deterministic gate with a consistent output is a policy — orchestration reduces auditability without adding any value here e.g. A flow that checks severity → blocks MR is a two-line policy rule, not a multi-step workflow

Misrouted

Is the outcome complex, multi-step, or context-dependent?

When a policy's expressiveness is insufficient — or the problem is cross-cutting — use agentic orchestration.

Examples

Chain actions across agents: triage → FP filter → assign → remediate → verify Because: Multi-step agent chaining that coordinates across agents can't be expressed as a single policy rule e.g. Finding detected → FP Agent scores it → if real, assign to team → trigger suggested fix → verify resolution

Agentic Orchestration

Combine SDLC context from Security + other departments to drive a security outcome Because: Cross-department context that drives an outcome is inherently multi-source — it can't be a single policy condition e.g. Security finding + deployment risk + team capacity signals → combined remediation priority decision

Agentic Orchestration

Deploy as a named playbook for repeatability Because: Named, repeatable flows belong in orchestration — playbooks are the orchestration equivalent of a policy rule e.g. "Critical Finding Remediation Playbook" that runs the same multi-step flow every time it's triggered

Agentic Orchestration

Using a policy rule to drive remediation priority based on combined SDLC context, FP confidence, and team capacity signals Why not: A policy acts on a single condition — it can't collect and reason across multiple agent signals before deciding. Anything requiring multi-source synthesis belongs in orchestration e.g. Remediation priority that factors in deployment risk + FP likelihood + team workload can't be expressed as a single trigger + rule + action

Misrouted

Phase 04

Govern

Define enforcement, accountability, and change control. Governance outcomes require consistency, traceability, and determinism — making Policy the right layer for most features in this phase. Exceptions: features that require multi-agent reasoning before an outcome is determined, or human-in-the-loop approval flows that produce recommendations rather than direct enforcement.

Answer these questions to find the right layer for your feature:

Is this outcome focused on enforcement or approval gates?

If the capability is about enforcing a requirement — blocking an action, requiring a review, or gating a transition — it belongs in Policy. Enforcement must be consistent and traceable to be meaningful.

Examples

Enforce a compliance requirement that blocks or gates an action until conditions are met Because: Enforcement gates require the consistency and auditability that only Policy can guarantee e.g. No critical finding can be closed without two approvals; scans must pass before deployment

Policy / Gov

Require that an automation or capability receive review or approval before taking effect Because: Gating the activation of automations is an enforcement concern — it belongs in Policy where it's traceable e.g. Any change to a scan policy must be approved by a security lead before publishing

Policy / Gov

Using an orchestration flow to check finding approval status before allowing deployment Why not: A consistent gate with a deterministic condition is a policy — building it as a flow removes the audit guarantee and adds complexity with no benefit e.g. A workflow that checks "are all critical findings resolved?" before deployment belongs in a scan execution policy, not a multi-step agent flow

Misrouted

Does this capability require full audit history or change tracking?

Policy-based actions produce consistent, traceable logs by design. Agentic orchestration can support governance workflows but shouldn't own them — auditability requires the consistency that only policy can guarantee.

Examples

Full audit log of who changed what, when, and what the outcome was Because: Policy-based actions produce traceable, consistent logs by design — the audit trail is guaranteed e.g. Every policy change, approval decision, and finding state transition logged with actor and timestamp

Policy / Gov

Track state transitions on findings, approvals, or compliance status over time Because: State transition tracking requires the determinism only Policy can guarantee — orchestration can support but not own governance e.g. Finding progresses: detected → triaged → assigned → remediated → verified → closed

Policy / Gov

Using an orchestration flow to track and log finding state transitions for compliance reporting Why not: Orchestration can't guarantee a consistent audit trail — if the flow changes or fails, the record breaks. Governance-grade logging requires the determinism that only Policy provides e.g. An agent that writes finding state changes to a spreadsheet isn't a reliable audit trail — state transitions should be policy-governed events with guaranteed logging

Misrouted

Does this agentic outcome require human review before it takes effect?

When an orchestration flow produces an automation or recommendation, a human-in-the-loop approval step may be required before it drives an outcome. The review gate is a Govern concern — surfaced as a platform-wide review queue, not a policy rule. The exception: if the approval step itself must be auditable and traceable, that enforcement belongs in Policy.

Examples

An agentic flow produces a recommendation or automation that must be reviewed before executing Because: The review gate is a Govern concern — a platform-wide queue, not a deterministic policy rule e.g. Agent recommends closing 12 findings as FPs → security lead reviews the batch before they're dismissed

Agentic Orchestration

The approval step itself must be auditable and traceable Because: When the approval act itself needs an audit trail, enforcement belongs in Policy — orchestration can't guarantee that e.g. The act of approving the agent's recommendation is logged as a policy-governed action

Policy / Gov

Writing a policy rule to require a security lead to approve every agentic recommendation before it executes Why not: A human review queue for agentic outputs isn't a condition a policy can evaluate — policies act on data states, not human availability. The review gate belongs in an orchestration workflow surfaced as a platform-wide approval queue e.g. "Require approval before agent closes findings" needs a review experience, not a blocking policy condition

Misrouted

03 Reference Hard edge cases, key distinctions between similar categories, and a glossary of framework terms.

Hard Cases

Hard Case 1

When does an orchestration flow graduate to a policy?

Orchestration flows are designed for contextual, multi-step decisions. But over time, some flows stabilize — they run on the same inputs and produce the same outputs every time. At that point they've become de facto policies implemented in the wrong layer.

If a flow produces the same output given the same input — and repeatability and auditability matter — promote it to a policy. Orchestration should handle the cases policy can't express, not the cases policy handles worse.

Signal to promote: You've run the same playbook 3+ times with identical inputs and outcomes. The step that's "just checking" before acting is always the same check. Stakeholders are asking for an audit trail.

Hard Case 2

What if a feature legitimately spans two categories?

Some features aren't purely one thing. A common pattern: Orchestration surfaces a recommendation, and Policy enforces the outcome. These aren't competing — orchestration can inform what policy gets written, and policy can trigger orchestration.

Design the boundary explicitly. Ask: where does the orchestration end and the policy begin? The handoff point is usually "a conclusion has been reached" — once the reasoning is done and a decision has been made, Policy takes over for enforcement.

Watch for: Features where orchestration is doing the reasoning and policy is doing the enforcing. This is the right pattern. The mistake is trying to put both in one layer.

Hard Case 3

Policy vs. Orchestration when the output is consistent but the reasoning is complex

Some decisions require complex multi-signal reasoning to arrive at a conclusion — but once arrived at, the conclusion is enforced the same way every time. This is the Policy/Orchestration seam, and it's the most common point of confusion.

Use Orchestration to reason, then Policy to enforce. Example: FP analysis reduces findings to a confidence score → Policy acts on the score threshold. The reasoning lives in Orchestration; the enforcement rule lives in Policy.

Signal you're in this case: The team keeps saying "but the logic is complex" about what should be a policy. Complex reasoning before a gate is fine — that's what orchestration is for. The gate itself is still a policy.

Hard Case 4

AI Configuration vs. Agentic Orchestration — what's the line?

Both involve agents. The distinction is about inputs vs. actions: AI Configuration defines what data is available to agents (context, enrichment sources, signal inputs). Agentic Orchestration defines what agents do with that data (actions, workflows, multi-step decisions).

If you're configuring what an agent sees → AI Configuration. If you're defining what an agent does → Agentic Orchestration.

Test: Can you describe the feature entirely in terms of data access and context availability? Then it's AI Configuration. Does it involve steps, actions, or decisions? Then it's Orchestration.

Hard Case 5

Requiring that a Scan Profile be applied — Policy or Scan Profiles?

There's a meaningful difference between defining what a profile contains and requiring that a profile be applied. These are separate concerns and should be designed separately.

Defining the profile's contents (which scanners, which branches, which conditions) → Scan Profiles. Requiring that the profile be applied to a project or pipeline → Policy. Scan config defines what the profile contains; Policy defines whether and where its use is required.

Watch for: Enforcement logic creeping into profile configuration. If the feature includes "must apply to," "required on," or similar language — that's a policy concern, not a scan config concern.

Key Design Distinctions

Scan profiles are about coverage, not Triage or Remediation outcomes — A scan profile defines what to scan, how broadly, and with what context. It shouldn't define what happens to the output. Outputs flow to Policy (enforcement) or Orchestration (contextual).
Data collection agents that don't serve coverage belong in AI Configuration — FP analysis and SDLC context agents enrich policy signals but don't help users get coverage. Their configuration belongs in a platform-wide AI Configuration experience, not in scan profiles alongside scanners.
Enforcing the use of profiles is a Policy concern, not a scan config concern — Requiring that a profile be applied to a project or pipeline is an enforcement rule — it belongs in Policy. Scan config defines what the profile contains; Policy defines whether and where its use is required.
Security agents are managed in AI Configuration and Agentic Orchestration — not in scan setup — Data collection agents (like FP Agent) live in AI Configuration. Agents that take action or drive workflows (like the SDLC Agent) live in Agentic Orchestration. Neither is configured as part of scan profiles.
Policies are enforcement rules, not just consistent functions — A policy is a Trigger + Rule + Action: same input → same output, every time. But what makes something a policy isn't just consistency — it's that it defines what must or must not happen. This applies beyond Security: branch protection, merge requirements, and approval gates are all policy-layer constructs.
Agentic orchestration is for complex, multi-signal outcomes — When you need to combine context from multiple agents, chain actions across steps, or solve a cross-cutting problem, use agentic orchestration. Security is one use case — this layer extends platform-wide.
Auditability favors policy — Policy-based actions produce consistent, traceable logs. Agentic orchestration reduces auditability. If a flow pattern repeats and auditability is becoming a concern, consider promoting it to policy.

Glossary

Agentic data collector: An AI agent whose primary role is gathering and enriching signals (e.g. FP likelihood, SDLC context) rather than taking action. These are configured in AI Configuration, not scan profiles.
AI Configuration: The platform-wide experience for configuring which data and context agentic systems can access. Covers enrichment sources, signal inputs, and agent data permissions. Not Security-specific.
Agentic Orchestration: A named, repeatable multi-step workflow executed by agents — combining context from multiple sources to drive decisions or actions that a single policy rule can't express.
FP analysis / FP Agent: False positive analysis. The FP Agent enriches findings with likelihood signals that inform whether a finding is a true positive. It is a data collection agent — configured in AI Configuration.
One-off Duo Interaction: A single, user-initiated Duo prompt or interaction. Not designed to scale or repeat. Useful for exploration, ad hoc analysis, or generating suggestions that a human then acts on.
Policy: A normative enforcement rule with the structure Trigger + Rule + Action. Policies define what must or must not happen, consistently, across every project and team. Full audit trail by design.
Scan Profiles: Configuration that defines which scanners run, on which projects and branches, and under what conditions. Governs coverage inputs only — not what happens to findings after a scan completes.
SDLC context / SDLC Agent: Software Development Lifecycle context — signals about pipeline state, deployment risk, code quality, team ownership, and branch activity. The SDLC Agent collects and surfaces this context for use in triage and remediation decisions.
SPP (Scan Policy Project): The GitLab project used to store and manage security policies. Enforcing that a group or project must use an SPP is a Policy concern; the contents of the policies within the SPP are Scan Profile or Policy concerns depending on their scope.
Trigger + Rule + Action: The canonical structure for a policy. Trigger: what event initiates the policy. Rule: the condition evaluated. Action: what happens when the condition is met. If a feature can't be expressed in this form, it likely belongs in Orchestration.