Skip to content

Add markdown formatting guidelines to daily-firewall-report workflow #11663

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Jan 24, 2026
+212 −58
Merged

Add markdown formatting guidelines to daily-firewall-report workflow #11663

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4c5eeb6
Initial plan
Copilot Jan 24, 2026
a4d05da
Add markdown formatting guidelines to daily-firewall-report workflow
Copilot Jan 24, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
136 changes: 107 additions & 29 deletions .github/workflows/daily-firewall-report.lock.yml
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

134 changes: 105 additions & 29 deletions .github/workflows/daily-firewall-report.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -144,6 +144,58 @@ If insufficient data is available (less than 7 days):

---

## 📝 Report Formatting Guidelines

**CRITICAL**: Follow these formatting guidelines to create well-structured, readable reports:

### 1. Header Levels
**Use h3 (###) or lower for all headers in your report to maintain proper document hierarchy.**

The discussion title serves as h1, so all content headers should start at h3:
- Use `###` for main sections (e.g., "### Executive Summary", "### Top Blocked Domains")
- Use `####` for subsections (e.g., "#### Blocked Domains by Workflow")
- Never use `##` (h2) or `#` (h1) in the report body

### 2. Progressive Disclosure
**Wrap detailed request logs and domain lists in `<details><summary><b>Section Name</b></summary>` tags to improve readability and reduce scrolling.**

Use collapsible sections for:
- Detailed request patterns and logs
- Per-workflow domain breakdowns (Section 3 below)
- Complete blocked domains list (Section 4 below)
- Verbose firewall data and statistics

Example:
```markdown
<details>
<summary><b>Full Request Log Details</b></summary>

[Long detailed content here...]

</details>
```

### 3. Report Structure Pattern

Your report should follow this structure for optimal readability:

1. **Brief Summary** (always visible): 1-2 paragraph overview of firewall activity
2. **Key Metrics** (always visible): Total requests, blocks, trends, block rate
3. **Top Blocked Domains** (always visible): Top 20 most frequently blocked domains in a table
4. **Detailed Request Patterns** (in `<details>` tags): Per-workflow breakdowns with domain tables
5. **Complete Blocked Domains List** (in `<details>` tags): Alphabetically sorted full list
6. **Security Recommendations** (always visible): Actionable insights and suggestions

### Design Principles

Create reports that:
- **Build trust through clarity**: Most important info (metrics, top domains, recommendations) immediately visible
- **Exceed expectations**: Add helpful context, trends, and security insights
- **Create delight**: Use progressive disclosure to reduce overwhelm for detailed data
- **Maintain consistency**: Follow the same patterns as other reporting workflows

---

## Objective

Generate a comprehensive daily report of all rejected domains across all agentic workflows that use the firewall feature. This helps identify:
Expand Down Expand Up @@ -293,12 +345,17 @@ Combine data from all workflows (using standardized metric names):

### Step 5: Generate Report

Create a comprehensive markdown report with the following sections:
Create a comprehensive markdown report following the formatting guidelines above. Structure your report as follows:

#### 1. Executive Summary
#### Section 1: Executive Summary (Always Visible)
A brief 1-2 paragraph overview including:
- Date of report (today's date)
- Total workflows analyzed (`workflow_runs_analyzed`)
- Total runs analyzed
- Total runs analyzed
- Overall firewall activity snapshot (key highlights, trends, concerns)

#### Section 2: Key Metrics (Always Visible)
Present the core statistics:
- Total network requests monitored (`firewall_requests_total`)
- ✅ **Allowed** (`firewall_requests_allowed`): Count of successful requests
- 🚫 **Blocked** (`firewall_requests_blocked`): Count of blocked requests
Expand All @@ -311,46 +368,59 @@ Create a comprehensive markdown report with the following sections:
> - A 0% block rate with listed blocked domains indicates domains that would
> be blocked if accessed, but weren't actually accessed during this period

#### 2. Top Blocked Domains
#### Section 3: Top Blocked Domains (Always Visible)
A table showing the most frequently blocked domains:
- Domain name
- Number of times blocked
- Workflows that blocked it
- Example URLs (if available)
- Domain category (Development Services, Social Media, Analytics/Tracking, CDN, Other)

Sort by frequency (most blocked first), show top 20.

#### 3. Blocked Domains by Workflow (Detailed)
#### Section 4: Detailed Request Patterns (In `<details>` Tags)
**IMPORTANT**: Wrap this entire section in a collapsible `<details>` block:

```markdown
<details>
<summary><b>View Detailed Request Patterns by Workflow</b></summary>

For each workflow that had blocked domains, provide a detailed breakdown:

**Workflow: [workflow-name]** (X runs analyzed)
#### Workflow: [workflow-name] (X runs analyzed)

| Domain | Blocked Count | Allowed Count | Block Rate | Category |
|--------|---------------|---------------|------------|----------|
| example.com | 15 | 5 | 75% | Social Media |
| api.example.org | 10 | 0 | 100% | Development |

For each workflow include:
- Workflow name and number of runs analyzed
- **Detailed domain table** with:
- Domain name
- Number of blocked requests to that domain
- Number of allowed requests to that domain (if any)
- Block rate percentage for that domain
- Domain category (Development Services, Social Media, Analytics/Tracking, CDN, Other)
- Total blocked requests for this workflow
- Total unique blocked domains
- Most frequently blocked domain

**Repeat this detailed breakdown for every workflow** that had blocked domains during the analysis period. This provides visibility into which specific workflows are generating blocks and for which exact domains.

#### 4. Complete Blocked Domains List
An alphabetically sorted list of all unique blocked domains with:
- Domain name
- Total occurrences across all workflows
- First seen date (from run timestamps)
- Total blocked requests: [count]
- Total unique blocked domains: [count]
- Most frequently blocked domain: [domain]

[Repeat for all workflows with blocked domains]

</details>
```

#### 5. Recommendations
Based on the analysis, provide:
#### Section 5: Complete Blocked Domains List (In `<details>` Tags)
**IMPORTANT**: Wrap this entire section in a collapsible `<details>` block:

```markdown
<details>
<summary><b>View Complete Blocked Domains List</b></summary>

An alphabetically sorted list of all unique blocked domains:

| Domain | Total Blocks | First Seen | Workflows |
|--------|--------------|------------|-----------|
| [domain] | [count] | [date] | [workflow-list] |
| ... | ... | ... | ... |

</details>
```

#### Section 6: Security Recommendations (Always Visible)
Based on the analysis, provide actionable insights:
- Domains that appear to be legitimate services that should be allowlisted
- Potential security concerns (e.g., suspicious domains)
- Suggestions for network permission improvements
Expand All @@ -361,7 +431,13 @@ Based on the analysis, provide:
Create a new GitHub discussion with:
- **Title**: "Daily Firewall Report - [Today's Date]"
- **Category**: audits
- **Body**: The complete markdown report generated in Step 5
- **Body**: The complete markdown report following the formatting guidelines and structure defined in Step 5

Ensure the discussion body:
- Uses h3 (###) for main section headers
- Uses h4 (####) for subsection headers
- Wraps detailed data (per-workflow breakdowns, complete domain list) in `<details>` tags
- Keeps critical information visible (summary, key metrics, top domains, recommendations)

## Notes

Expand Down
Loading