diff --git a/docs-site/src/content/docs/reference/cli-reference.md b/docs-site/src/content/docs/reference/cli-reference.md index c09bd84af..463a3d035 100644 --- a/docs-site/src/content/docs/reference/cli-reference.md +++ b/docs-site/src/content/docs/reference/cli-reference.md @@ -232,6 +232,118 @@ awf logs --source running -f Log sources are auto-discovered in this order: running containers, `AWF_LOGS_DIR` environment variable, then preserved log directories in `/tmp/squid-logs-*`. ::: +### `awf logs stats` + +Show aggregated statistics from firewall logs. + +```bash +awf logs stats [options] +``` + +:::note[stats vs summary] +Use `awf logs stats` for terminal output (defaults to colorized `pretty` format). Use `awf logs summary` for CI/CD integration (defaults to `markdown` format for `$GITHUB_STEP_SUMMARY`). Both commands provide the same data in different default formats. +::: + +#### Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `--format ` | string | `pretty` | Output format: `json`, `markdown`, `pretty` | +| `--source ` | string | auto | Path to log directory or `running` for live container | + +#### Output Formats + +| Format | Description | +|--------|-------------| +| `pretty` | Colorized terminal output with summary and domain breakdown (default) | +| `markdown` | Markdown table format suitable for documentation | +| `json` | Structured JSON for programmatic consumption | + +#### Examples + +```bash +# Show stats with colorized terminal output +awf logs stats + +# Get stats in JSON format for scripting +awf logs stats --format json + +# Get stats in markdown format +awf logs stats --format markdown + +# Use a specific log directory +awf logs stats --source /tmp/squid-logs-1234567890 +``` + +#### Example Output (Pretty) + +``` +Firewall Statistics +──────────────────────────────────────── + +Total Requests: 150 +Allowed: 145 (96.7%) +Denied: 5 (3.3%) +Unique Domains: 12 + +Domains: + api.github.com 50 allowed, 0 denied + registry.npmjs.org 95 allowed, 0 denied + evil.com 0 allowed, 5 denied +``` + +### `awf logs summary` + +Generate summary report optimized for GitHub Actions step summaries. + +```bash +awf logs summary [options] +``` + +#### Options + +| Option | Type | Default | Description | +|--------|------|---------|-------------| +| `--format ` | string | `markdown` | Output format: `json`, `markdown`, `pretty` | +| `--source ` | string | auto | Path to log directory or `running` for live container | + +:::tip[GitHub Actions] +The `summary` command defaults to markdown format, making it perfect for piping directly to `$GITHUB_STEP_SUMMARY`. +::: + +#### Examples + +```bash +# Generate markdown summary (default) +awf logs summary + +# Add to GitHub Actions step summary +awf logs summary >> $GITHUB_STEP_SUMMARY + +# Get summary in JSON format +awf logs summary --format json + +# Get summary with colorized terminal output +awf logs summary --format pretty +``` + +#### Example Output (Markdown) + +```markdown +### Firewall Activity + +
+150 requests | 145 allowed | 5 blocked | 12 unique domains + +| Domain | Allowed | Denied | +|--------|---------|--------| +| api.github.com | 50 | 0 | +| registry.npmjs.org | 95 | 0 | +| evil.com | 0 | 5 | + +
+``` + ## See Also - [Quick Start Guide](/gh-aw-firewall/quickstart) - Getting started with examples diff --git a/docs/github_actions.md b/docs/github_actions.md index 8f7b81bc5..76b09868b 100644 --- a/docs/github_actions.md +++ b/docs/github_actions.md @@ -87,6 +87,79 @@ If you currently have manual Squid proxy configuration, you can replace it with 'copilot --prompt "..."' ``` +## Generating Firewall Summaries + +The `awf logs summary` command generates markdown output optimized for GitHub Actions step summaries, eliminating the need for manual log parsing scripts. + +### Basic Usage + +```yaml +- name: Run command through firewall + run: | + sudo awf \ + --allow-domains github.com,api.github.com \ + 'your-command-here' + +- name: Generate firewall summary + if: always() + run: awf logs summary >> $GITHUB_STEP_SUMMARY +``` + +### Complete Example + +```yaml +jobs: + test: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + + - name: Install Firewall + run: | + curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash + + - name: Test with Firewall + env: + GITHUB_TOKEN: ${{ secrets.COPILOT_CLI_TOKEN }} + run: | + sudo -E awf \ + --allow-domains github.com,api.github.com,registry.npmjs.org \ + 'npx @github/copilot@latest --prompt "Hello"' + + - name: Generate firewall summary + if: always() + run: awf logs summary >> $GITHUB_STEP_SUMMARY +``` + +The summary appears as a collapsible section in your workflow run showing: +- Total requests, allowed, and blocked counts +- Table of all domains with their allowed/denied request counts + +### Output Formats + +```bash +# Default: Markdown (for $GITHUB_STEP_SUMMARY) +awf logs summary + +# JSON format for programmatic processing +awf logs summary --format json + +# Pretty format for terminal output +awf logs summary --format pretty +``` + +### Getting Statistics + +For detailed statistics without adding to step summary: + +```bash +# Pretty terminal output +awf logs stats + +# JSON for scripting +awf logs stats --format json +``` + ## MCP Server Configuration for Copilot CLI ### Overview diff --git a/docs/logging_quickref.md b/docs/logging_quickref.md index 24a106c66..e750d7e11 100644 --- a/docs/logging_quickref.md +++ b/docs/logging_quickref.md @@ -188,24 +188,50 @@ docker exec awf-squid grep "curl" /var/log/squid/access.log ## Statistics -### Total Requests +### Using `awf logs stats` + +Get aggregated statistics including total requests, allowed/denied counts, and per-domain breakdown: + +```bash +# Pretty terminal output (default) +awf logs stats + +# JSON format for scripting +awf logs stats --format json + +# Markdown format +awf logs stats --format markdown +``` + +### Using `awf logs summary` for GitHub Actions + +Generate a markdown summary optimized for GitHub Actions step summaries: + +```bash +# Add summary to GitHub Actions step summary +awf logs summary >> $GITHUB_STEP_SUMMARY +``` + +### Manual Statistics Queries + +#### Total Requests ```bash docker exec awf-squid wc -l /var/log/squid/access.log ``` -### Blocked vs Allowed Count +#### Blocked vs Allowed Count ```bash echo "Blocked: $(docker exec awf-squid grep -c TCP_DENIED /var/log/squid/access.log)" echo "Allowed: $(docker exec awf-squid grep -cE 'TCP_TUNNEL|TCP_MISS' /var/log/squid/access.log)" ``` -### Top 10 Accessed Domains +#### Top 10 Accessed Domains ```bash docker exec awf-squid awk '{print $3}' /var/log/squid/access.log | \ sort | uniq -c | sort -rn | head -10 ``` -### Unique Client IPs +#### Unique Client IPs ```bash docker exec awf-squid awk '{split($2,a,":"); print a[1]}' /var/log/squid/access.log | sort -u ``` diff --git a/docs/usage.md b/docs/usage.md index eb7329a23..350c3c0da 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -538,6 +538,52 @@ awf logs --format json | jq -s 'group_by(.isAllowed) | map({allowed: .[0].isAllo ## Log Analysis +### Using `awf logs stats` + +Get aggregated statistics from firewall logs including total requests, allowed/denied counts, and per-domain breakdown: + +```bash +# Pretty terminal output (default) +awf logs stats + +# JSON format for scripting +awf logs stats --format json + +# Markdown format +awf logs stats --format markdown +``` + +Example output: +``` +Firewall Statistics +──────────────────────────────────────── + +Total Requests: 150 +Allowed: 145 (96.7%) +Denied: 5 (3.3%) +Unique Domains: 12 + +Domains: + api.github.com 50 allowed, 0 denied + registry.npmjs.org 95 allowed, 0 denied + evil.com 0 allowed, 5 denied +``` + +### Using `awf logs summary` (GitHub Actions) + +Generate a markdown summary optimized for GitHub Actions: + +```bash +# Generate markdown summary and append to step summary +awf logs summary >> $GITHUB_STEP_SUMMARY +``` + +This creates a collapsible summary in your GitHub Actions workflow output showing all allowed and blocked domains. + +### Manual Log Queries + +For more granular analysis, you can query the logs directly: + Find all blocked domains: ```bash docker exec awf-squid grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $3}' | sort -u