opensource/kilocode
3
0
Fork 0
mirror of https://github.com/Kilo-Org/kilocode.git synced 2026-08-28 19:11:03 +08:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #11369 from Kilo-Org/docs/security-agent-guide

Browse Source 
docs(kilo-docs): expand Security Agent guide
This commit is contained in:
Jean du Plessis
2026-06-24 17:17:44 +02:00
committed by GitHub
parent f9b3579a78 1da0d3c82e
commit 3044ab168e
2 changed files with 403 additions and 111 deletions
Download Patch File Download Diff File Expand all files Collapse all files
packages/kilo-docs/lib/nav/deploy-secure.ts
+1 -1
View File
@@ -10,6 +10,6 @@ export const DeploySecureNav: NavSection[] = [
},
{
title: "Security",
links: [{ href: "/deploy-secure/security-reviews", children: "Security Reviews" }],
links: [{ href: "/deploy-secure/security-reviews", children: "Security Agent" }],
},
]
packages/kilo-docs/pages/deploy-secure/security-reviews.md
+402 -110
View File
@@ -1,199 +1,491 @@
---
title: "Security Reviews"
description: "Contextualize dependency vulnerabilities with AI"
title: "Security Agent"
description: "Manage and remediate GitHub Dependabot alerts with AI"
---
# Security Reviews
# Security Agent
Most teams are drowning in Dependabot alerts. The majority of reported CVEs aren't actually exploitable because the vulnerable code path is never used — but figuring that out manually doesn't scale.
Security Agent syncs dependency vulnerability alerts from selected GitHub repositories and stores them as Security Findings in Kilo. It uses AI to triage each finding and runs sandbox analysis when project-specific evidence is needed. It also helps you dismiss or remediate findings, send notifications, and review recorded activity.
Kilo's Security Agent fixes this. It syncs your Dependabot alerts, triages them with AI, and performs deep codebase analysis to determine whether each vulnerability is actually reachable in your code. Non-exploitable findings can be auto-dismissed and synced back to GitHub.
Available for all users.
---
Use Security Agent to identify reachable Dependabot alerts, prioritize findings, and see which findings the analysis recommends dismissing or remediating with a pull request.
## Prerequisites
You need three things before enabling Security Reviews:
Before enabling Security Agent, make sure you have:
1. The [KiloConnect GitHub App](/docs/automate/integrations#connecting-github) installed with `vulnerability_alerts` permission
2. [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts) enabled on your target repositories
3. Kilo Code credits for AI model usage
1. The [Kilo GitHub App](/docs/automate/integrations#connecting-github) installed with the `vulnerability_alerts` permission.
2. [Dependabot alerts](https://docs.github.com/en/code-security/dependabot/dependabot-alerts) enabled on target repositories.
3. Kilo Code credits for AI model usage.
---
Security Agent currently works with GitHub Dependabot alerts. If the GitHub App loses required permissions, Security Agent prompts you to re-authorize the app before syncing or analyzing findings.
## Get started
1. Go to the **Security Agent** page — either from your [personal dashboard](https://app.kilo.ai/security-agent) or your organization's dashboard
2. Connect GitHub if you haven't already via the [Integrations page](/docs/automate/integrations)
3. Choose which repositories the agent should monitor (all or specific ones)
4. Toggle the agent on — this kicks off an initial sync of your Dependabot alerts
1. Open Security Agent from your personal dashboard or an organization dashboard.
2. If GitHub is not connected, connect it from the Integrations page.
3. Choose a repository scope: all repositories available to the Kilo GitHub App or selected repositories.
4. Turn on Security Agent.
5. Review the General, Automation, Notifications, and SLA settings.
The agent syncs alerts every 6 hours automatically after that. You can trigger a manual sync at any time from the Findings page.
Turning on Security Agent queues an initial sync for the selected repository scope. It then syncs Dependabot alerts every 6 hours. You can also trigger a manual sync from the dashboard or Findings page.
---
## Organization permissions
## Understand the pipeline
Organization members can view the Security Agent dashboard, findings, and analysis evidence. They can also trigger manual syncs, start or retry analysis, start or retry remediation, and request remediation cancellation.
The Security Agent processes each vulnerability alert through four stages.
Organization owners and billing managers can change Security Agent settings, turn the agent on or off, dismiss findings, clear orphaned findings, and access organization audit reports. Kilo platform admins can also access these reports for audited support and operations.
**Sync** pulls Dependabot alerts from your connected repositories on a 6-hour cycle.
Access to organization notifications is more restricted than access to settings: Security Agent emails go only to current organization owners.
**Triage** runs a quick LLM assessment of the alert metadata — the advisory, severity, package, and version range. Each finding gets classified as **Safe to Dismiss**, **Needs Analysis**, or **Needs Review**.
## How Security Agent works
**Deep analysis** kicks in for findings that warrant it. The Cloud Agent performs a full codebase search for actual usage of the vulnerable package, checks whether the vulnerable code paths are reachable, and suggests fixes when possible.
Security Agent processes dependency vulnerability alerts through several stages. The main finding flow is:
**Auto-dismiss** (when enabled) automatically closes non-exploitable findings and syncs that dismissal back to GitHub with a `[Kilo Code auto-dismiss]` prefix.
```mermaid
flowchart LR
alert["Dependabot alert"] --> sync["Sync into Kilo"]
sync --> triage["AI triage"]
triage --> action["Dismiss, review, or remediate"]
triage -. "When needed" .-> analysis["Sandbox analysis"]
analysis --> action
```
---
Notifications and audit recording run alongside this workflow.
## Choose an analysis mode
1. **Sync** pulls Dependabot alerts from repositories in scope and stores them as Security Findings in Kilo.
2. **Triage** quickly assesses advisory metadata with AI, including package, severity, vulnerable range, patched version, and advisory text.
3. **Sandbox analysis** uses Cloud Agent to inspect the codebase when Security Agent needs project-specific evidence.
4. **Auto-dismiss** can dismiss findings that analysis determines are not exploitable, then sync the dismissal back to GitHub.
5. **Remediation** can ask Cloud Agent to create a pull request for an eligible exploitable finding.
6. **Notifications** can email eligible recipients about new findings and SLA events.
7. **Audit reports** show recorded Security Finding activity for a selected reporting period.
You control how much analysis the agent performs via three modes:
| Mode | What happens |
|---|---|
| **Auto** | Triage first, then deep analysis only when triage recommends it |
| **Shallow** | Triage only — no deep analysis |
| **Deep** | Full codebase analysis for every finding, regardless of triage result |
**Auto** is the default. It gives you the best balance between thoroughness and credit usage — deep analysis only runs where triage says it's needed.
---
Security Agent treats Dependabot alerts as source data and Kilo Security Findings as the working record. A finding can stay open even after a remediation PR exists. The finding closes only when GitHub reports it fixed or someone dismisses it.
## Use the dashboard
The dashboard is the Security Agent's landing page. It gives you a high-level view of your security posture, and every widget links through to the Findings page with the relevant filters applied. Use the repository filter at the top to scope everything to specific repos.
The dashboard shows your current security posture and can be filtered by repository. Use the repository filter to show metrics for one repository or all repositories.
**SLA compliance** is the hero metric — your overall compliance percentage with a per-severity breakdown, linking directly to any overdue findings.
When SLA tracking is enabled, the dashboard shows:
**Severity breakdown** shows open finding counts across Critical, High, Medium, and Low in a 2×2 grid. Click any severity to see those findings.
| Metric | Meaning |
|---|---|
| SLA compliance | Percentage of open findings whose deadlines remain within SLA. |
| Deadline passed | Open findings whose persisted SLA deadlines have passed. |
| Due this week | Open findings approaching their deadline, including confirmed exploitable findings. |
| No deadline | Open findings without evidence of an assigned SLA deadline. |
**Finding status** is a donut chart of Open, Fixed, and Dismissed findings. Click a segment to filter the Findings page.
When SLA tracking is disabled, the dashboard focuses on action posture:
**Analysis coverage** shows a progress bar of analyzed vs. total findings, with an outcome breakdown (Exploitable, Not Exploitable, Safe to Dismiss, etc.).
| Metric | Meaning |
|---|---|
| Open findings | Current open finding count by severity. |
| Confirmed exploitable | Findings where sandbox analysis confirmed project risk. |
| Needs your review | Findings that need a human decision. |
| Analysis not complete | Findings whose project-specific risk is still unknown. |
**Mean time to resolution** compares your average resolution time per severity against your configured SLA targets.
**Overdue findings** lists the top 10 findings past their SLA deadline — severity, title, repo, package, and how many days overdue.
**Repository health** is a per-repo summary with severity counts, overdue count, and SLA compliance percentage.
---
The dashboard also highlights one finding to address first. It prioritizes overdue findings, findings needing analysis, exploitable findings, and findings needing human review. Dashboard links open the Findings page with matching filters.
## Browse findings
The Findings page is where you work through your vulnerability backlog. At the top, a summary bar shows open/closed counts, your current analysis capacity, when the last sync ran, and a **Sync** button for manual refreshes.
The Findings page is where you work through the vulnerability backlog.
Filter findings by repository, severity, outcome, or sort order to focus on what matters most. Each row shows a severity badge, the finding title and package name, its current outcome label, and an action button — **Analyze**, **Retry**, **Review**, or **View Details** depending on state.
Use filters and sorting to focus the list:
Findings past their SLA deadline are highlighted in red so they're easy to spot. The page paginates at 20 results and auto-refreshes every 5 seconds when analyses are running.
| Control | Options |
|---|---|
| Repository | All repositories or one repository in Security Agent scope. |
| Severity | Critical, High, Medium, Low. |
| Outcome | Not analyzed, Analysis failed, Exploitable, Not exploitable, Safe to dismiss, Needs review, Triage complete, Fixed, Dismissed. |
| Sort | Severity descending, severity ascending, or SLA due date when SLA tracking is enabled. |
---
Each row shows severity, title, package, analysis outcome, remediation status, and next action. Common actions include Analyze, Retry, Review, Fix, View PR, Retry fix, Cancel, and View details.
The Findings page shows current analysis capacity and the last sync time. It displays 20 findings per page and refreshes automatically while analysis or remediation is active.
## Inspect a finding
Click any finding to open its detail dialog. There are three tabs.
Click a finding to open its detail dialog, which has three tabs.
The **Details** tab shows the vulnerability metadata — package name and ecosystem, CVE and GHSA IDs, the vulnerable and patched version ranges, manifest path, and a full description. You'll also find a **View on GitHub** link to the original Dependabot alert, plus detection and last sync dates.
### Details
The **Triage** tab shows the agent's initial assessment: a suggested action badge (Safe to Dismiss, Needs Analysis, or Needs Review), a confidence level, and the reasoning behind the decision. If triage hasn't run yet, you can start it here. If it failed, you can retry.
The Details tab shows source vulnerability metadata:
The **Analysis** tab shows the deep analysis results when available — whether the vulnerability is exploitable or not, a summary, up to 5 usage locations found in your codebase, a suggested fix, and full analysis details. There's also a link to continue the investigation in Cloud Agent if you want to dig deeper.
- package name and ecosystem;
- CVE and GHSA identifiers;
- vulnerable version range and patched version;
- manifest path;
- severity and status;
- repository and Dependabot source link;
- detection, sync, and SLA timing when available.
---
If another finding superseded it, the Details tab links to the current canonical finding.
### Analysis
The Analysis tab shows evidence from triage and sandbox analysis.
Triage can classify a finding as Safe to dismiss, Needs analysis, or Needs review. Depending on the evidence, sandbox analysis can classify a finding as Exploitable, Not exploitable, Monitor, Manual review, or Open PR.
The Analysis tab shows current progress, failure state, model details, reasoning, usage locations, the suggested fix, and the next action. You can start analysis, retry a failed analysis, restart an active analysis when supported, or start remediation when the finding is eligible.
### Remediation
The Remediation tab explains whether Security Agent can start a remediation attempt and why. It also shows remediation history, active attempts, PR outcomes, reasons for failure or blocking, validation evidence, risk notes, cancellation state, and the model used.
Available remediation actions depend on server-side safety checks. You may see Start remediation, Retry remediation, Cancel remediation, or View PR.
## Understand statuses and outcomes
Every finding has a **primary status** and an **outcome label**. The status tracks the overall lifecycle, while the outcome reflects what the AI determined.
**Primary status:**
A finding's primary status tracks its source lifecycle:
| Status | Meaning |
|---|---|
| Open | Active vulnerability that needs attention |
| Fixed | Resolved — detected from the Dependabot alert state |
| Dismissed | Closed by a user or by auto-dismiss |
| Open | Active Security Finding that still needs resolution or dismissal. |
| Fixed | Dependabot reports the alert as fixed. |
| Dismissed | Manual dismissal or auto-dismiss closed the finding and synced the dismissal to GitHub. |
| Superseded | Finding was replaced by a canonical finding after duplicate consolidation. |
**Outcome labels:**
The analysis outcome reflects what the AI analysis determined:
| Outcome | Meaning |
|---|---|
| Not Analyzed | No analysis has run yet |
| Analyzing | Analysis is currently in progress |
| Analysis Failed | Something went wrong during analysis |
| Exploitable | Deep analysis confirmed it's exploitable |
| Not Exploitable | Deep analysis confirmed it's not reachable |
| Safe to Dismiss | Triage recommends dismissing this finding |
| Needs Review | Triage recommends manual review |
| Triage Complete | Triage is done, no deep analysis needed |
| Not analyzed | No analysis has completed. |
| Queued | Analysis is waiting to run. |
| Analyzing | Analysis is running. |
| Analysis failed | Analysis did not complete. |
| Exploitable | Sandbox analysis confirmed reachable project risk. |
| Not exploitable | Sandbox analysis found no reachable vulnerable path. |
| Safe to dismiss | Triage recommends dismissal. |
| Needs review | Human decision required. |
| Triage complete | Triage finished and no sandbox result is present. |
---
The remediation status tracks Cloud Agent fix attempts:
| Status | Meaning |
|---|---|
| Queued | The remediation attempt has been accepted and is waiting to run. |
| Starting | Cloud Agent launch is being prepared. |
| Running | Cloud Agent is working on the remediation. |
| Cancellation requested | User asked Cloud Agent to stop; cancellation is best effort. |
| PR opened | Security Agent verified a remediation PR for the expected repository and branch. |
| No changes needed | Cloud Agent found no code change to make. Finding remains open. |
| Blocked | Security Agent or Cloud Agent could not proceed safely. |
| Failed | Attempt ended with failure. |
| Cancelled | Attempt stopped without opening a PR. |
## Dismiss findings
There are two ways findings get dismissed.
You can dismiss a finding manually from its details. Manual dismissal requires a reason:
**Manually**, you select a finding and choose **Dismiss**. You'll pick a reason — Fix started, No bandwidth, Tolerable risk, Inaccurate, or Not used — and optionally add a comment. The dismissal syncs back to GitHub and closes the corresponding Dependabot alert.
- Fix started
- No bandwidth
- Tolerable risk
- Inaccurate
- Not used
**Automatically**, when auto-dismiss is enabled, the agent closes findings on its own. After deep analysis, any finding determined to be not exploitable is dismissed immediately. After triage, findings with a "dismiss" recommendation are dismissed if they meet your configured confidence threshold. All auto-dismissed alerts are written back to GitHub with a `[Kilo Code auto-dismiss]` prefix.
You can optionally add a comment. A manual dismissal syncs to GitHub and closes the matching Dependabot alert.
---
When enabled, auto-dismiss automatically dismisses findings that sandbox analysis determines are not exploitable and recommends dismissing. It can also dismiss triage-only findings that recommend dismissal and meet the configured confidence threshold. Security Agent attempts to write each auto-dismissed finding back to GitHub with a `[Kilo Code auto-dismiss]` prefix. See [Configure auto-dismiss](#configure-auto-dismiss) for threshold behavior.
## Configure the agent
## Remediate findings
All settings are on the Security Agent configuration page.
Remediation creates a Security Remediation Attempt and asks Cloud Agent to prepare a fix. If Cloud Agent can make a safe change, it opens a pull request in the affected repository.
**Repository selection** lets you monitor all repositories accessible to the KiloConnect App or pick specific ones from a list.
Starting remediation does not mark the Security Finding fixed. A remediation PR is evidence of work in progress. The finding remains open until Dependabot reports it fixed or someone dismisses it.
**AI models** can be configured separately for triage and deep analysis. The default is Claude Opus 4.6.
### Manual remediation
**Analysis mode** controls the pipeline — Auto (triage then selective deep analysis), Shallow (triage only), or Deep (full analysis on everything). See [Choose an analysis mode](#choose-an-analysis-mode) for details.
You can start manual remediation from an eligible finding even when Auto Remediation is disabled. Manual remediation does not have to meet the Auto Remediation severity threshold.
**Auto-analysis** toggles whether new findings are analyzed automatically. When on, you set a minimum severity threshold (Critical only, High+, Medium+, or All) and whether to include findings that existed before you enabled the feature.
The following safety gates still apply to manual remediation:
**Auto-dismiss** toggles automatic dismissal of non-exploitable findings. You configure a confidence threshold: High only, Medium+, or Any. The "Any" option dismisses at any confidence level — use it with caution.
- the finding is open;
- Security Agent is enabled;
- the repository is still in Security Agent scope;
- sandbox analysis is complete and fresh for the current finding data;
- analysis provides a concrete fix path;
- no active remediation attempt exists;
- no known remediation PR exists for the finding.
**SLA deadlines** set how many days your team has to remediate findings at each severity level:
Manual remediation can proceed when exploitability is unknown or the result requires manual review, provided a concrete fix path is available. Monitor-only findings remain ineligible for one-click remediation.
| Severity | Default |
### Auto remediation
Auto Remediation is off by default. When enabled, Security Agent can start remediation automatically only for findings that pass all these gates:
- the finding is open;
- the repository is in Security Agent scope;
- sandbox analysis is complete and fresh;
- the finding is exploitable;
- analysis recommends opening a PR;
- analysis provides a concrete fix path;
- severity meets the configured Auto Remediation threshold;
- there is no active attempt, known PR, or duplicate automatic terminal result.
Auto Remediation applies to future findings after their analysis completes. If Include existing findings is enabled, it also queues eligible findings that have already been analyzed. Duplicate PRs and duplicate automatic attempts for the same analysis result remain suppressed.
### Retry and cancel
You can retry an attempt that failed, was blocked or cancelled, or ended with no changes needed, provided the finding still passes the safety gates and no PR has opened.
You can cancel a queued or running attempt. Cancellation is best effort. If Cloud Agent opens a verified PR before cancellation completes, Security Agent shows the status as PR opened.
## Configure Security Agent
Settings are split into four tabs: General, Automation, Notifications, and SLA.
### General
General settings include:
| Setting | Default | Notes |
|---|---|---|
| Security Agent enabled | Off until you turn it on | Turning it on queues an initial sync for the selected repository scope. |
| Repository selection | Selected repositories during setup | Choose all accessible repositories or selected repositories. |
| Triage model | Kilo Balanced | Used for initial triage and exploitability recommendations. |
| Analysis model | Kilo Balanced | Used for sandbox analysis and result extraction. |
| Remediation model | Kilo Balanced | Used by Cloud Agent for remediation PR work. |
| Analysis mode | Auto | Auto, Shallow, or Deep. |
#### Turn Security Agent on or off
Turning on Security Agent checks the GitHub App permissions and queues an initial sync for the current repository scope. Scheduled syncs then run every 6 hours.
Turning it off stops scheduled syncs and prevents new automatic analysis, remediation, and notification work. It does not delete existing findings or audit history, and it does not cancel a remediation attempt that is already running. Authorized users can still open existing [audit reports](#audit-reports).
#### Choose repository scope
Repository scope controls which Dependabot alerts Security Agent syncs:
- **All repositories** includes every repository currently available to the Kilo GitHub App.
- **Selected repositories** includes only the repositories you choose.
Changing the scope affects future syncs and remediation eligibility. Removing a repository from scope does not close its existing findings. Open findings remain eligible for SLA tracking until they are fixed, dismissed, superseded, or deleted. If the GitHub App can no longer access a repository, its findings become orphaned and can be removed through [Clear orphaned findings](#clear-orphaned-findings).
#### Choose models
Security Agent uses a separate model for each stage:
- The Triage model reviews advisory metadata and makes the initial exploitability recommendation.
- The Analysis model runs sandbox analysis and extracts the result.
- The Remediation model is used by Cloud Agent to prepare remediation pull requests.
Kilo Balanced is the default for all three stages. You can change each model independently. The model recorded in finding details is the model used when that analysis or remediation attempt ran. AI triage, sandbox analysis, and remediation consume Kilo Code credits.
#### Choose an analysis mode
Analysis mode controls how Security Agent analyzes a finding after syncing it.
| Mode | What happens |
|---|---|
| Critical | 15 days |
| High | 30 days |
| Medium | 45 days |
| Low | 90 days |
| Auto | Run triage first, then sandbox analysis only when triage recommends it. |
| Shallow | Run triage only. Sandbox analysis does not run automatically. |
| Deep | Run sandbox analysis for every finding. |
You can adjust these per your organization's policies and reset to defaults at any time.
Auto is the default. It runs sandbox analysis only when triage determines that codebase-level analysis is needed, which limits sandbox-analysis credit usage.
---
### Automation
Automation settings include:
| Setting | Default | Notes |
|---|---|---|
| Auto-analysis | Off | Automatically analyzes synced findings. |
| Auto-analysis minimum severity | High and above | Critical only, High and above, Medium and above, or All severities. |
| Auto-analysis include existing | Off | Queues previously synced eligible findings. |
| Auto-remediation | Off | Automatically starts remediation for eligible exploitable findings; successful attempts open PRs. |
| Auto-remediation minimum severity | High and above | Critical only, High and above, Medium and above, or All severities. |
| Auto-remediation include existing | Off | Queues already-analyzed eligible findings; duplicate PRs stay suppressed. |
| Auto-dismiss | Off | Automatically dismisses findings that analysis determines are not exploitable and recommends dismissing. |
| Auto-dismiss confidence threshold | High confidence only | High confidence only, Medium or higher, or Any confidence. |
#### Configure auto-analysis
Auto-analysis is off by default. When enabled, it queues open findings that are first synced after activation and meet the minimum severity:
- **Critical only** analyzes critical findings.
- **High and above** analyzes high and critical findings.
- **Medium and above** analyzes medium, high, and critical findings.
- **All severities** analyzes every finding, including findings whose severity is unknown.
Without Include existing findings, previously synced findings are not added to the automatic-analysis backlog. Turning on Include existing findings queues eligible open findings that already exist in Kilo. Re-enabling Auto-analysis while Include existing findings remains on also checks that backlog. This can use additional credits.
The selected [analysis mode](#choose-an-analysis-mode) controls the depth of each automatic analysis. Auto-analysis shares per-owner analysis capacity with manual analysis, so a large backlog may take time to finish.
#### Configure auto-remediation
Auto-remediation acts only on eligible findings that meet its minimum severity, using the same cumulative severity bands as Auto-analysis. Include existing findings also applies the policy to eligible findings whose sandbox analysis is already complete. Re-enabling Auto-remediation or lowering its severity threshold while Include existing findings is on checks the existing backlog again. Duplicate PRs and duplicate automatic attempts remain suppressed.
The automatic severity threshold does not restrict manual remediation. See [Auto remediation](#auto-remediation) for the complete eligibility and safety gates, or [Manual remediation](#manual-remediation) for user-triggered fixes.
#### Configure auto-dismiss
Auto-dismiss uses the confidence threshold only for triage-only findings that AI recommends dismissing:
- **High confidence only** accepts only high-confidence recommendations.
- **Medium or higher** accepts medium- and high-confidence recommendations.
- **Any confidence** accepts low-, medium-, and high-confidence recommendations. Use this option with caution.
The confidence threshold does not apply after sandbox analysis. When sandbox analysis determines that a finding is not exploitable and recommends dismissal, Auto-dismiss can dismiss it regardless of confidence. Enabling Auto-dismiss does not start analysis by itself; it applies when an analysis produces an eligible result.
Security Agent records the dismissal in Kilo and attempts to sync it to GitHub with a `[Kilo Code auto-dismiss]` prefix. A GitHub write-back failure does not reopen the local finding. See [Dismiss findings](#dismiss-findings) for manual dismissal behavior.
### Notifications
The Notifications tab controls New-finding Notifications.
| Setting | Default | Notes |
|---|---|---|
| New-finding Notifications | Off | Sends an email when Kilo first inserts an eligible open finding. |
| New-finding minimum severity | High and above | Critical only, High and above, Medium and above, or Low and above. |
#### New-finding notifications
A New-finding Notification is eligible only when Kilo first inserts an open finding whose severity meets the configured minimum. Severity thresholds are cumulative: for example, High and above includes high and critical findings. Later updates, severity changes, and reopening do not make an existing finding new again. Lowering the severity threshold also does not replay earlier findings.
Existing Dependabot alerts discovered during the first Security Agent sync count as new because that sync is the first time Kilo inserts them. Enabling New-finding Notifications later does not replay those historical insertions.
For a personal Security Agent, emails go to the owning user. For an organization Security Agent, they go only to current organization owners. Members and billing managers receive these notifications only if they are also organization owners. See [Notification delivery](#notification-delivery) for delivery checks and deduplication behavior.
### SLA
The SLA tab controls remediation deadlines and SLA notifications.
| Setting | Default | Notes |
|---|---|---|
| SLA tracking | On | Controls SLA dashboard posture and warning or breach eligibility. |
| Critical deadline | 15 days | Editable from 1 to 365 days. |
| High deadline | 30 days | Editable from 1 to 365 days. |
| Medium deadline | 45 days | Editable from 1 to 365 days. |
| Low deadline | 90 days | Editable from 1 to 365 days. |
| SLA notifications | Off | Sends warning and breach emails. |
| SLA notification minimum severity | High and above | Critical only, High and above, Medium and above, or Low and above. |
| SLA warning lead time | 3 days | Whole number from 1 to 365 days. |
#### How SLA deadlines work
Security Agent calculates a finding's deadline from the date GitHub first detected the Dependabot alert and the configured number of days for its severity. When a later sync changes the finding's severity or uses updated deadline settings, Security Agent refreshes the persisted deadline.
Turning off SLA tracking removes SLA posture from the dashboard and makes findings ineligible for SLA Warning and SLA Breach Notifications. It does not close findings, remove their persisted deadlines, or erase recorded activity. Security Agent continues to refresh deadlines when it syncs findings.
#### SLA notifications
SLA notifications require both SLA tracking and SLA notifications to be enabled. The minimum severity is cumulative, and warning lead time controls how many whole days before the persisted deadline a warning becomes eligible. See [Notification delivery](#notification-delivery) for exact timing, deduplication, and setting-change behavior.
## Notification delivery
Security Agent currently sends notifications only by email.
Notification kinds:
| Kind | When eligible |
|---|---|
| New-finding Notification | Kilo first inserts an eligible open finding. |
| SLA Warning Notification | Eligible open finding enters configured warning window before persisted SLA deadline. |
| SLA Breach Notification | Eligible open finding reaches or passes persisted SLA deadline. |
A finding that is already breached does not receive a stale warning. A warning sent earlier does not suppress the later breach notification. If you enable SLA notifications later, an eligible open finding can produce its current warning or breach during the next evaluation.
Security Agent creates at most one notification of each kind per finding and recipient. Syncs and sweeps do not intentionally create duplicate notification events. Sent notifications are not replayed when settings change.
Delivery is asynchronous. Before sending an email, Kilo rechecks the current finding state, Security Agent settings, severity thresholds, SLA state, and recipient authorization. Kilo cancels unsent notification work if the finding is fixed, dismissed, superseded, deleted, or no longer meets the configured threshold, or if the recipient is no longer authorized.
Email subjects are:
| Kind | Subject |
|---|---|
| New finding | Kilo Security Agent: New finding |
| SLA warning | Kilo Security Agent: SLA warning |
| SLA breach | Kilo Security Agent: SLA breached |
Emails include finding severity, repository, title, description, CVE/GHSA/CVSS metadata when available, the SLA deadline for SLA emails, a link to Security Agent findings, and a link to the relevant notification settings.
## Audit reports
The audit report shows Security Finding activity recorded for an owner during a selected reporting period. Open it from Security Agent navigation at the applicable route:
- `/security-agent/audit-report`
- `/organizations/:organizationId/security-agent/audit-report`
The audit report is based on activity recorded by Kilo. It does not prove that every historical event is present, show repository scan coverage, or provide aggregate SLA compliance.
### Report period and filters
By default, the report covers the last 90 calendar days, ending today. A reporting period cannot exceed 90 inclusive calendar days. Kilo rejects future or reversed ranges.
Filters:
| Filter | Options |
|---|---|
| Reporting period | Date range up to 90 inclusive calendar days. |
| Severity | All, Critical, High, Medium, Low. |
| Recorded state | All, Open, Fixed, Dismissed, Superseded, Deleted. |
| Repository | All repositories or one repository recorded in report evidence. |
For each matching finding group, filters retain the complete timeline within the selected period.
### Report content
The report starts with summary counts for findings, events, superseded findings, and severity. It then groups activity by Security Finding, combining relevant repository, package, advisory, status, and SLA context with a timeline for the selected period.
Each timeline event shows when Kilo recorded or applied the activity, who or what performed it, and the evidence needed to understand the outcome. Superseded and deleted findings retain their recorded identity and lifecycle context.
### Reportable activity
The audit report includes material Security Finding activity recorded during the selected period:
- a finding imported into Kilo;
- a severity change;
- a status change, including reopened and fixed;
- manual dismissal, auto-dismissal, supersession, or deletion;
- terminal analysis completion or failure;
- a remediation request;
- remediation ending with PR opened, failed, blocked, cancelled, or no changes needed.
The audit report excludes reads, page views, unchanged sync observations, queue claims, heartbeats, and retries with no new finding-level outcome. It also excludes notification delivery history, repository scan-coverage appendices, configuration timelines, and report-generation events within the report itself.
If a report query fails, times out, or exceeds its budget, Kilo returns no report content rather than partial results. Choose a shorter reporting period and generate the report again.
### Report access
Personal audit reports are available to the owning user.
Organization audit reports are available to organization owners, billing managers, and Kilo platform admins. Under current route permissions, organization members who are not owners or billing managers can use other Security Agent surfaces but cannot access organization audit reports.
Security Agent does not need to be enabled to view an existing report. The report page is available after GitHub integration and the initial Security Agent configuration have been set up. Setup-only states redirect to Settings.
## Clear orphaned findings
If repositories are removed from your GitHub integration or become inaccessible, their findings become orphaned. When this happens, a card appears on the settings page to permanently delete them.
If repositories are removed from GitHub integration or become inaccessible, their findings can become orphaned. The Settings page shows a cleanup card when orphaned repositories exist.
{% callout type="warning" %}
Clearing orphaned findings is permanent and cannot be undone. Only do this when you're sure the repositories won't be reconnected.
Clearing orphaned findings permanently deletes findings for the selected repository. You cannot undo this action. Use it only if the repository will not be reconnected.
{% /callout %}
---
## Compare with Code Reviews
Kilo offers two complementary security features that work best together.
Security Agent and Code Reviews cover different security surfaces.
[**Code Reviews**](/docs/automate/code-reviews/overview) analyzes PR diffs for code quality issues, including security patterns like `innerHTML` usage and hardcoded secrets. It catches problems in new code as it's written.
| Feature | What it covers |
|---|---|
| Code Reviews | Pull request diffs, including security patterns in new code. |
| Security Agent | Dependency vulnerability alerts across selected repositories, including reachability analysis and remediation for Dependabot findings. |
**Security Reviews** takes a different angle — it contextualizes dependency vulnerability alerts across your entire codebase to determine whether Dependabot-reported CVEs are actually exploitable based on how your code uses the affected packages.
Together, Code Reviews covers your new code surface and Security Reviews covers your dependency vulnerability surface.
---
Use Code Reviews to catch risky changes before they are merged. Use Security Agent to manage the dependency vulnerability backlog and determine which Dependabot alerts are exploitable in your codebase.
## Limitations
Security Reviews currently works with **GitHub only** — GitLab support is not yet available.
The following capabilities are not yet implemented but are being considered for upcoming releases of the Security Agent.
The only data source right now is **Dependabot alerts**. Additional sources like npm audit and SBOM analysis are planned.
There is a **per-account limit** on concurrent analyses. If you have a large backlog, findings will be queued and processed in order.
- GitLab support for Security Agent findings and remediation.
- Security Finding sources beyond Dependabot alerts, such as npm audit and SBOM analysis.
- Notification channels beyond email.
- Historical replay when you enable New-finding Notifications.
- Analysis and remediation without queue delays. This work currently runs through queues and can be delayed by account capacity or worker backlog.
- Automatic finding updates based on the full remediation PR lifecycle. A finding currently closes only when Dependabot reports it fixed or someone dismisses it.
- Planned remediations that combine multiple Security Findings.
- Repository write-permission checks when you configure Security Agent.
- Audit report periods longer than 90 days.
- Complete legacy-history reconstruction and aggregate historical SLA compliance percentages.
- Server-stored report artifacts, PDFs, report caching, and exhaustive notification delivery history.