> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryflare.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Incident Scope

> On-demand audit log analysis for security incidents with correlated timeline narrative

# Incident Scope

Incident Scope is an on-demand analysis tool for security incidents. Point it at a time window, and Flare pulls your cloud audit logs, reconstructs a correlated timeline, and creates a GitHub Issue with a plain-English narrative of what happened.

Unlike scheduled runs and deploy webhooks (which run automatically), Incident Scope is triggered manually when you're investigating a specific event -- an alert, a suspicious login, a compromised credential, or a pager notification at 2am.

<Note>
  Incident Scope requires an active GCP connector. Set up your [GCP connector](/connectors/gcp) first. Authentication uses an API key (not a webhook token).
</Note>

## How it works

1. You trigger the workflow manually from GitHub Actions, specifying the incident time window
2. Flare fetches all audit logs within that window (up to 5,000 events, severity-prioritized)
3. AI analyzes the logs with an incident-focused prompt that looks for lateral movement, privilege escalation, and cross-service correlation
4. A GitHub Issue is created with a narrative summary and a chronological timeline table

## Setting up

### 1. Create an API key

1. Go to **Settings** at [tryflare.ai](https://www.tryflare.ai)
2. Create an API key (starts with `flr_pr_`)
3. Add it as a repository secret: **Settings > Secrets > Actions > New repository secret** named `FLARE_API_KEY`

### 2. Add the workflow

Create `.github/workflows/incident-scope.yml` in your repository:

```yaml theme={null}
name: Incident Scope

on:
  workflow_dispatch:
    inputs:
      time_from:
        description: 'Start of incident window (ISO 8601)'
        required: true
      time_to:
        description: 'End of incident window (ISO 8601, default: now)'
        required: false
        default: ''

jobs:
  scope:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    steps:
      - uses: tryflare-ai/incident-scope@v1
        with:
          token: ${{ secrets.FLARE_API_KEY }}
          time-from: ${{ inputs.time_from }}
          time-to: ${{ inputs.time_to }}
```

### 3. Trigger during an incident

From your repository's **Actions** tab, click **Incident Scope > Run workflow**. Enter the start time of the incident window in ISO 8601 format (e.g., `2026-06-07T02:00:00Z`). Leave `time_to` empty to use the current time.

## What Flare detects

The incident analysis focuses on patterns that matter during active investigations:

| Pattern                         | What it catches                                                  |
| ------------------------------- | ---------------------------------------------------------------- |
| **Timeline reconstruction**     | Cross-service event ordering to show the sequence of actions     |
| **Lateral movement**            | When one action enables access in a different service or project |
| **Privilege escalation**        | Self-grants, IAM policy changes, service account key creation    |
| **Data access patterns**        | Who accessed which data stores and when                          |
| **Permission failure clusters** | PERMISSION\_DENIED spikes that suggest reconnaissance            |
| **Persistence mechanisms**      | New service accounts, exported keys, modified IAM policies       |

## What the Issue contains

Each Incident Scope run creates a GitHub Issue with:

* **Narrative** -- AI-synthesized plain-English summary of what happened, written like an incident report
* **Timeline table** -- chronological events with timestamp, service, actor, action, and severity
* **Severity counts** -- critical, high, and medium findings at a glance
* **Truncation notice** -- if log volume exceeded 5,000 events, which events were kept (severity-prioritized)

## Inputs

| Input             | Required | Default                                               | Description                                                                      |
| ----------------- | -------- | ----------------------------------------------------- | -------------------------------------------------------------------------------- |
| `token`           | Yes      | --                                                    | Flare API key (`flr_pr_...`). Generate from Settings at tryflare.ai.             |
| `time-from`       | Yes      | --                                                    | Start of incident window (ISO 8601).                                             |
| `time-to`         | No       | now                                                   | End of incident window (ISO 8601).                                               |
| `connector-id`    | No       | most recent                                           | Flare connector ID. If omitted, uses the most recently created active connector. |
| `severity-filter` | No       | `all`                                                 | Minimum severity floor: `all`, `medium`, `high`, `critical`.                     |
| `api-url`         | No       | `https://www.tryflare.ai/api/webhooks/incident-scope` | Override for self-hosted.                                                        |

## Outputs

| Output         | Description                                              |
| -------------- | -------------------------------------------------------- |
| `issue-url`    | URL of the created GitHub Issue with incident findings.  |
| `total-events` | Total audit log events analyzed.                         |
| `truncated`    | Whether logs were capped due to volume (`true`/`false`). |

## Examples

### Filter to high and critical only

```yaml theme={null}
- uses: tryflare-ai/incident-scope@v1
  with:
    token: ${{ secrets.FLARE_API_KEY }}
    time-from: '2026-06-07T02:00:00Z'
    time-to: '2026-06-07T06:00:00Z'
    severity-filter: 'high'
```

### Specific connector

```yaml theme={null}
- uses: tryflare-ai/incident-scope@v1
  with:
    token: ${{ secrets.FLARE_API_KEY }}
    time-from: '2026-06-07T02:00:00Z'
    connector-id: 'a487e0b3-f489-400a-914a-ff8becdd3303'
```

### Use the output

```yaml theme={null}
- name: Incident scope
  id: scope
  uses: tryflare-ai/incident-scope@v1
  with:
    token: ${{ secrets.FLARE_API_KEY }}
    time-from: '2026-06-07T02:00:00Z'

- name: Notify Slack
  if: steps.scope.outputs.issue-url != ''
  run: |
    curl -X POST "$SLACK_WEBHOOK" \
      -d "{\"text\": \"Incident scope complete: ${{ steps.scope.outputs.total-events }} events analyzed. ${{ steps.scope.outputs.issue-url }}\"}"
```

## Limits

| Limit               | Value                                               |
| ------------------- | --------------------------------------------------- |
| Maximum time window | 24 hours                                            |
| Maximum events      | 5,000 (severity-prioritized truncation if exceeded) |
| Daily limit         | 10 analyses/day (shared across all Flare features)  |
| Latency             | Under 90 seconds for windows under 4 hours          |

When more than 5,000 events exist in the time window, Flare keeps events by severity priority (critical first, then high, medium, and informational) to maximize signal within the cap.

## Combining with other Flare Actions

Incident Scope is the reactive complement to the proactive Flare Actions:

* **[Scheduled runs](/scheduled-runs)** detect anomalies continuously
* **[Deploy webhooks](/deploy-webhooks)** catch deployment-related regressions
* **[Security Changelog](/security-changelog)** provides weekly trend summaries
* **Incident Scope** gives you deep-dive analysis when something goes wrong

A typical incident workflow: a scheduled run flags unusual IAM activity, you get paged, and you trigger Incident Scope with the alert timestamp to get the full picture.