> ## 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.

# Security Changelog

> Weekly AI-synthesized cloud security summary delivered as a GitHub Issue and committed Markdown

# Security Changelog

The Security Changelog produces a weekly AI-synthesized summary of your cloud security activity. Instead of sifting through thousands of audit log entries, you get a concise "weather report" that tells you what happened this week, what changed from last week, and what deserves attention.

The output is committed to your repo as Markdown and structured JSON, creating a Git-versioned history of your cloud security posture. A GitHub Issue is also created with a risk label so the right people see it.

<Note>
  The Security Changelog requires an active GCP connector with a scheduled analysis configured. Set up your [GCP connector](/connectors/gcp) and [scheduled runs](/scheduled-runs) first.
</Note>

## How it works

1. The Action runs on a weekly cron schedule in your GitHub Actions workflow
2. Flare fetches 7 days of cloud audit logs from your connected GCP environment
3. AI analyzes the logs and produces a structured changelog with risk scoring
4. The Action commits `SECURITY-CHANGELOG.md` and `security-changelog.json` to your repo
5. A GitHub Issue is created with the summary, risk score, and risk label

Over time, `git log SECURITY-CHANGELOG.md` becomes a narrative timeline of your cloud security posture. The structured JSON enables risk score trending and automated alerting.

## Setting up

### 1. Prerequisites

* A Flare account with a connected GCP connector ([sign up](https://www.tryflare.ai/sign-up))
* An active scheduled analysis (go to **Connectors** and enable a schedule)
* A webhook token (go to **Connectors**, click **Generate webhook token**)

### 2. Add the workflow

Create `.github/workflows/security-changelog.yml` in your repository:

```yaml theme={null}
name: Security Changelog

on:
  schedule:
    - cron: '0 9 * * 1'  # Every Monday at 9am UTC
  workflow_dispatch:       # Manual trigger for testing

permissions:
  contents: write
  issues: write

jobs:
  changelog:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Generate security changelog
        uses: tryflare-ai/security-changelog@v1
        with:
          token: ${{ secrets.FLARE_WEBHOOK_TOKEN }}
```

### 3. Add the secret

Go to your repository's **Settings > Secrets and variables > Actions > New repository secret**. Name it `FLARE_WEBHOOK_TOKEN` and paste your webhook token.

### 4. Test it

Trigger the workflow manually from the **Actions** tab using the "Run workflow" button. The first run will produce a baseline changelog with all trends set to "new". Subsequent runs will include week-over-week comparisons.

## What the changelog covers

Each week's analysis categorizes findings into:

| Category               | What it covers                                                       |
| ---------------------- | -------------------------------------------------------------------- |
| **Identity changes**   | New service accounts, key rotations, unusual principal activity      |
| **Permission changes** | IAM role grants, policy updates, binding changes                     |
| **Access anomalies**   | Cross-region access, unusual API call patterns, off-hours activity   |
| **Resource changes**   | Compute instance operations, storage changes, network modifications  |
| **Error patterns**     | PERMISSION\_DENIED spikes, quota exhaustion, authentication failures |

### Risk scoring

Every changelog includes a risk score from 0 to 10:

| Score | Meaning                                                                    |
| ----- | -------------------------------------------------------------------------- |
| 0     | Quiet week -- no meaningful security activity                              |
| 1-3   | Routine operations, nothing unusual                                        |
| 4-6   | Notable changes worth awareness (new service accounts, permission changes) |
| 7-8   | Significant security events requiring review                               |
| 9-10  | Critical activity requiring immediate investigation                        |

### Week-over-week comparison

When a prior week's `security-changelog.json` exists in your repo, the changelog automatically includes:

* **Category trends** -- each category is marked as up, down, or flat compared to the prior week
* **Risk score delta** -- the signed change in risk score (e.g., "+1.2", "-0.5")
* **Comparison summary** -- a one-sentence summary of the most important changes

On the first run, all trends are set to "new" (no baseline for comparison). The comparison block is omitted entirely.

### Quiet week handling

If no meaningful security activity occurred:

* Risk score is set to 0
* All category counts are 0
* Highlights array is empty
* The Markdown says "No significant cloud security changes detected during this period"

The changelog is still committed -- the absence of activity is itself a data point.

## Inputs

| Input            | Required | Default                   | Description                                                                  |
| ---------------- | -------- | ------------------------- | ---------------------------------------------------------------------------- |
| `token`          | Yes      | --                        | Flare webhook token (starts with `flr_`). Generate from the Connectors page. |
| `period`         | No       | `7d`                      | Analysis period: `7d` for weekly or `1d` for daily.                          |
| `changelog-path` | No       | `SECURITY-CHANGELOG.md`   | Path to the changelog Markdown file.                                         |
| `json-path`      | No       | `security-changelog.json` | Path to the structured JSON file.                                            |
| `create-issue`   | No       | `true`                    | Create a GitHub Issue with the changelog summary.                            |
| `api-url`        | No       | `https://www.tryflare.ai` | Flare API base URL.                                                          |

## Outputs

| Output         | Description                                                 |
| -------------- | ----------------------------------------------------------- |
| `risk-score`   | Risk score from 0-10 assigned by the analysis               |
| `total-events` | Total audit log events analyzed (shows `N+` when sampled)   |
| `issue-url`    | URL of the created GitHub Issue (if `create-issue` is true) |

## What gets committed

Each run produces two files:

* **`SECURITY-CHANGELOG.md`** -- Human-readable Markdown. New entries are prepended, so the most recent week is always at the top.
* **`security-changelog.json`** -- Structured JSON with risk scores, category counts, and highlights. Overwritten each run (latest week only; full history is in git). Used automatically for week-over-week comparison on the next run.

Commits are authored as `flare-ai[bot]` with the message format: `security: weekly changelog (risk: N/10)`.

## Examples

### Daily changelog

```yaml theme={null}
- name: Generate daily security changelog
  uses: tryflare-ai/security-changelog@v1
  with:
    token: ${{ secrets.FLARE_WEBHOOK_TOKEN }}
    period: '1d'
    changelog-path: 'SECURITY-DAILY.md'
    json-path: 'security-daily.json'
```

### Changelog without Issue

```yaml theme={null}
- name: Generate security changelog
  uses: tryflare-ai/security-changelog@v1
  with:
    token: ${{ secrets.FLARE_WEBHOOK_TOKEN }}
    create-issue: 'false'
```

### Alert on high risk

```yaml theme={null}
- name: Generate security changelog
  id: changelog
  uses: tryflare-ai/security-changelog@v1
  with:
    token: ${{ secrets.FLARE_WEBHOOK_TOKEN }}

- name: Alert on high risk
  if: steps.changelog.outputs.risk-score >= 7
  run: echo "::warning::High risk score detected: ${{ steps.changelog.outputs.risk-score }}/10"
```

### Custom file paths

```yaml theme={null}
- name: Generate security changelog
  uses: tryflare-ai/security-changelog@v1
  with:
    token: ${{ secrets.FLARE_WEBHOOK_TOKEN }}
    changelog-path: 'docs/security/CHANGELOG.md'
    json-path: 'docs/security/changelog.json'
```

## JSON schema

The `security-changelog.json` file follows this structure:

```json theme={null}
{
  "version": 1,
  "generated_at": "2026-06-07T09:00:00Z",
  "period": { "start": "2026-05-31T09:00:00Z", "end": "2026-06-07T09:00:00Z" },
  "source": "gcp",
  "risk_score": 4.5,
  "total_events": 12847,
  "categories": {
    "identity_changes": { "count": 2, "trend": "up", "details": "..." },
    "permission_changes": { "count": 5, "trend": "flat", "details": "..." },
    "access_anomalies": { "count": 1, "trend": "down", "details": "..." },
    "resource_changes": { "count": 8, "trend": "flat", "details": "..." }
  },
  "highlights": [
    {
      "severity": "high",
      "title": "New service account with admin role",
      "description": "...",
      "resource": "sa-name@project.iam.gserviceaccount.com",
      "source": "gcp"
    }
  ],
  "comparison": {
    "vs_prior_week": true,
    "risk_delta": "+1.2",
    "summary": "IAM activity up 40% from prior week."
  }
}
```

The `comparison` block is only present when prior week data was available. The `version` field allows the schema to evolve in future releases.

## Combining with other Flare Actions

The Security Changelog works alongside the other Flare GitHub Actions:

* **[Scheduled runs](/scheduled-runs)** catch anomalies in real-time
* **[Deploy webhooks](/deploy-webhooks)** catch anomalies introduced by deployments
* **[PR Security Check](/pr-security-check)** reviews IaC changes before they merge
* **Security Changelog** provides the weekly summary and trend tracking

All four can run on the same connector. Each serves a different time horizon: PR checks prevent issues, deploy webhooks catch immediate regressions, scheduled runs detect ongoing anomalies, and the changelog gives you the big picture.