stackql-audit-template

Run deterministic cross-cloud security audits directly from GitHub Actions using OIDC — then automatically publish a live findings page with history via GitHub Pages. No credenitals stored in github.

What This Template Does

This repository:

• Runs on-demand cross-cloud audits from GitHub Actions
• Queries AWS, GCP and Azure using provider-native APIs
• Generates structured findings and trend history
• Republishes a static findings site via GitHub Pages
• Stores immutable audit snapshots as JSON history
• Uses OIDC authentication (no stored cloud credentials)

The result is a self-updating cloud posture site with zero backend infrastructure.

Interested in any way — using it, extending it, or partnering? Email actions@stackql.io. We'd love to hear from you.

---

Quick Start

1. Use This Template

Click:

Use this template

Create your own repository from this template.

---

2. Configure OIDC + Secrets

Set up cloud trust for GitHub Actions OIDC, then add the matching secrets under:

Settings
→ Secrets and variables
→ Actions
→ New repository secret

You only need secrets for the clouds you want to audit — leave the rest unset and those providers are skipped automatically.

Cloud	Repository secrets
AWS	STACKQL_ID_FED_AWS_ROLE_ARN
GCP	STACKQL_ID_FED_GCP_WORKLOAD_IDENTITY_PROVIDER, STACKQL_ID_FED_GCP_SERVICE_ACCOUNT
Azure / Entra	STACKQL_ID_FED_AZURE_TENANT_ID, STACKQL_ID_FED_AZURE_CLIENT_ID — plus optional STACKQL_ID_FED_AZURE_SUBSCRIPTION_ID (scopes to one subscription; omit to scan all)

Grant read-only access only. Exact roles per provider and the OIDC trust setup are in → docs/required-auth.md.

GCP note: the gcp-org audit also needs the google-org-id workflow input at run time. Skipping GCP entirely? Just leave the GCP secrets unset.

---

3. Run The Workflow

Actions
→ Cloud Audit Pages (OIDC)
→ Run workflow

The first run creates the gh-pages branch with your findings. (Do this before enabling Pages — the branch doesn't exist until the first run.)

---

4. Enable GitHub Pages

Once the first run finishes:

Settings
→ Pages
→ Deploy from branch
→ gh-pages
→ / (root)

---

5. Open Your Findings Page

GitHub assigns the URL — you don't construct it yourself. Find it under:

Settings → Pages

The box at the top reads "Your site is live at https://…" — click that link (or the Visit site button next to it).

---

What Gets Published

The workflow updates the gh-pages branch with:

index.html

audit/
  latest.json
  previous.json
  diff-latest.json
  trend-30d.json

  runs/
    <timestamp>.json

This provides:

• immutable audit history
• trend analysis
• latest findings
• reproducible outputs
• downloadable artifacts

---

Design Goals

• deterministic outputs
• provider-native interrogation
• GitHub-native workflows
• zero backend infrastructure
• reproducible findings
• forkable deployment model

This is not an “AI SOC analyst”.

This is deterministic multi-cloud audit and reporting.

---

Authentication

This template uses GitHub Actions OIDC — no long-lived cloud credentials are stored. Each cloud authenticates via short-lived federated tokens, and any cloud whose secrets are unset is skipped automatically.

---

Repository Structure

What ships in this template:

.github/workflows/
  audit-oidc.yml          # the audit + publish workflow
docs/
  required-auth.md        # exact per-cloud roles + OIDC trust setup
README.md

The audit output (index.html, audit/latest.json, history under audit/runs/) is generated by the workflow and published to the gh-pages branch — it does not exist in this branch until the first run.

---

Get In Touch

Using this template, hitting a snag, or want to talk integration / partnership?

→ Email actions@stackql.io — every message is read.

---

StackQL

Powered by StackQL:

https://github.com/stackql/stackql