Risk Flagger Workflow

The Risk Flagger workflow analyzes code changes for security risks that require security team investigation. Unlike traditional vulnerability scanners, this workflow focuses on identifying changes that could introduce security risks, making it ideal for pull request analysis and change management.

Overview

Workflow ID: risk_flagger
Primary Use Case: Risk assessment of code changes and pull requests
Output: Risk findings and optional GitHub notifications
Required Mode: Must use --diff mode

Common Use Cases

1. Pull Request Security Gate

CLI
GitHub Actions

# Automated PR analysis with team notification
fraim run risk_flagger --location . --diff --base main --head HEAD \
  --pr-url https://github.com/owner/repo/pull/123 \
  --approver security-team \
  --custom-risk-list-json '{"Example Rule": "Flag this rule on every diff, it is an example to show how the workflow works."}' \
  --custom-risk-list-action replace

2. Custom Risk Categories

CLI
GitHub Actions

# Organization-specific risk assessment
fraim run risk_flagger --location . --diff \
  --custom-risk-list-filepath ./org-risks.yaml \
  --custom-false-positive-considerations \
    "Ignore test files in /tests/" \
    "Skip demo applications"

3. Release Branch Analysis

CLI
GitHub Actions

# Analyze changes between releases
fraim run risk_flagger --location . --diff \
  --base v1.0.0 \
  --head v1.1.0 \
  --confidence 6

4. Pre-Commit Risk Assessment

# Local risk check before committing
fraim run risk_flagger --location . --diff \
  --confidence 8

Workflow-Specific Options

Required Options

`--diff`

Required: The risk flagger workflow must run in diff mode.

fraim run risk_flagger --location . --diff

GitHub Integration Options

`--pr-url <URL>`

URL of the pull request to analyze for GitHub integration.

fraim run risk_flagger --location . --diff \
  --pr-url https://github.com/owner/repo/pull/123

`--approver <USERNAME>`

GitHub username or team to notify when risks are found.

fraim run risk_flagger --location . --diff \
  --pr-url https://github.com/owner/repo/pull/123 \
  --approver security-team

`--no-gh-comment <BOOLEAN>`

Set to true to disable GitHub comments for risk findings. Useful when you want to use only Slack notifications or other notification methods. Default: false

fraim run risk_flagger --location . --diff \
  --no-gh-comment true

`--should-block-pull-request <BOOLEAN>` (GitHub Action only)

Whether to block the pull request until security review is complete. Available only when using the GitHub Action. Default: false

# In GitHub Action workflow_args
"should-block-pull-request": true

`--slack-webhook-url <URL>`

Provide a Slack webhook URL to send risk notifications to your team’s Slack channel.

fraim run risk_flagger --location . --diff \
  --slack-webhook-url https://hooks.slack.com/services/YOUR/WEBHOOK/URL

# In GitHub Action workflow_args
"slack-webhook-url": "${{ secrets.SLACK_WEBHOOK_URL }}"

Customization Options

`--custom-risk-list-action <append|replace>`

How to handle custom risk lists. Default: append

# Add custom risks to default list
fraim run risk_flagger --location . --diff \
  --custom-risk-list-action append

# Replace default risks with custom ones
fraim run risk_flagger --location . --diff \
  --custom-risk-list-action replace

`--custom-risk-list-filepath <PATH>`

Path to JSON/YAML file containing additional risks.

fraim run risk_flagger --location . --diff \
  --custom-risk-list-filepath ./custom-risks.yaml

Example custom-risks.yaml:

"API Endpoint Changes": "Changes to API endpoints that handle sensitive data should be reviewed by the security team"
"Payment Processing": "Any changes to payment processing logic require security review"
"User Data Handling": "Modifications to user data processing need privacy team approval"

`--custom-risk-list-json <JSON>`

JSON string containing additional risks.

fraim run risk_flagger --location . --diff \
  --custom-risk-list-json '{"Custom Risk": "Description of the risk"}'

`--custom-false-positive-considerations <LIST>`

Additional considerations to reduce false positives.

fraim run risk_flagger --location . --diff \
  --custom-false-positive-considerations \
    "Ignore test files" \
    "Consider demo code as low risk" \
    "Skip configuration templates"

GitHub Actions Integration

Easy Setup
GitHub App
Block Pull Request

Simple setup with no GitHub token requiredWhat this does:

✅ Adds risk assessment comments to pull requests
❌ No team notifications or reviewer requests
❌ No status checks or PR blocking

name: Risk Assessment
on:
  pull_request:
    branches: [main]

permissions:
  contents: read
  actions: read
  pull-requests: write

jobs:
  risk-assessment:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
        with:
          fetch-depth: 0
      
      - name: Run Fraim Risk Flagger Scan
        uses: fraim-dev/fraim-action@423d9d6b3c80923557887930d80eec4ca22a5c24
        with:
          workflow: risk_flagger
          workflow_args: |
            {
              "approver": "fraim-dev/security",
              "custom-risk-list-json": {
                "Example Risk": "Never flag this risk, it is just an example."
              },
              "custom-risk-list-action": "append"
            }
          anthropic-api-key: ${{ secrets.ANTHROPIC_API_KEY }}

Available workflow_args

Argument	Type	Default	Description
`approver`	string	`""`	GitHub username or group to notify for approval
`should-block-pull-request`	boolean	`false`	Whether to block the pull request until security review is complete
`custom-risk-list-action`	string	`"append"`	Whether to `"append"` to or `"replace"` the default risks list
`custom-risk-list-filepath`	string	`null`	Path to JSON/YAML file containing additional risks
`custom-risk-list-json`	object	`null`	JSON object containing additional risks to consider
`custom-false-positive-considerations`	array of strings	`[]`	List of additional considerations to help reduce false positives
`slack-webhook-url`	string	`null`	Provide a Slack webhook URL to send notifications
`no-gh-comment`	boolean	`false`	Set to `true` to disable GitHub comments for risk findings
`confidence`	integer (1-10)	`7`	Minimum confidence threshold for filtering findings
`chunk-size`	integer	`500`	Number of lines per chunk
`limit`	integer	`null`	Limit the number of files to scan
`globs`	array of strings	`null`	File patterns to include (uses workflow defaults if not provided)
`max-concurrent-chunks`	integer	`5`	Maximum number of chunks to process concurrently
`github-app-id`	string	No	GitHub App ID for enhanced GitHub integration (enables team notifications and PR blocking)
`github-app-private-key`	string	No	GitHub App private key for enhanced GitHub integration (enables team notifications and PR blocking)

Get Started

Workflows

Integrations

CLI

Risk Flagger

Risk Flagger Workflow

Overview

Common Use Cases

1. Pull Request Security Gate

2. Custom Risk Categories

3. Release Branch Analysis

4. Pre-Commit Risk Assessment

Workflow-Specific Options

Required Options

`--diff`

GitHub Integration Options

`--pr-url <URL>`

`--approver <USERNAME>`

`--no-gh-comment <BOOLEAN>`

`--should-block-pull-request <BOOLEAN>` (GitHub Action only)

`--slack-webhook-url <URL>`

Customization Options

`--custom-risk-list-action <append|replace>`

`--custom-risk-list-filepath <PATH>`

`--custom-risk-list-json <JSON>`

`--custom-false-positive-considerations <LIST>`

GitHub Actions Integration

Available workflow_args

Get Started

Workflows

Integrations

CLI

​Risk Flagger Workflow

​Overview

​Common Use Cases

​1. Pull Request Security Gate

​2. Custom Risk Categories

​3. Release Branch Analysis

​4. Pre-Commit Risk Assessment

​Workflow-Specific Options

​Required Options

​--diff

​GitHub Integration Options

​--pr-url <URL>

​--approver <USERNAME>

​--no-gh-comment <BOOLEAN>

​--should-block-pull-request <BOOLEAN> (GitHub Action only)

​--slack-webhook-url <URL>

​Customization Options

​--custom-risk-list-action <append|replace>

​--custom-risk-list-filepath <PATH>

​--custom-risk-list-json <JSON>

​--custom-false-positive-considerations <LIST>

​GitHub Actions Integration

​Available workflow_args

Risk Flagger Workflow

Overview

Common Use Cases

1. Pull Request Security Gate

2. Custom Risk Categories

3. Release Branch Analysis

4. Pre-Commit Risk Assessment

Workflow-Specific Options

Required Options

`--diff`

GitHub Integration Options

`--pr-url <URL>`

`--approver <USERNAME>`

`--no-gh-comment <BOOLEAN>`

`--should-block-pull-request <BOOLEAN>` (GitHub Action only)

`--slack-webhook-url <URL>`

Customization Options

`--custom-risk-list-action <append|replace>`

`--custom-risk-list-filepath <PATH>`

`--custom-risk-list-json <JSON>`

`--custom-false-positive-considerations <LIST>`

GitHub Actions Integration

Available workflow_args