diff --git a/.github/ISSUE_TEMPLATE/security_report.yml b/.github/ISSUE_TEMPLATE/security_report.yml new file mode 100644 index 0000000..6f11f07 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/security_report.yml @@ -0,0 +1,36 @@ +name: Security Report (Public Placeholder) +description: Use this only if private advisory reporting is unavailable. +title: "[Security]: " +labels: ["security"] +body: + - type: markdown + attributes: + value: | + For sensitive vulnerabilities, please use GitHub Security Advisories for private disclosure. + + - type: textarea + id: summary + attributes: + label: Summary + description: Short description of the issue. + placeholder: Describe the vulnerability. + validations: + required: true + + - type: textarea + id: steps + attributes: + label: Reproduction Steps + description: Exact steps to reproduce. + placeholder: 1. Do this... 2. Do that... + validations: + required: true + + - type: textarea + id: impact + attributes: + label: Impact + description: What can an attacker do? + placeholder: Impact details. + validations: + required: true diff --git a/.github/workflows/deploy-website.yml b/.github/workflows/deploy-website.yml new file mode 100644 index 0000000..8149d9a --- /dev/null +++ b/.github/workflows/deploy-website.yml @@ -0,0 +1,41 @@ +name: Deploy Docs Website + +on: + push: + branches: ["main"] + paths: + - "website/**" + - ".github/workflows/deploy-website.yml" + workflow_dispatch: + +permissions: + contents: read + pages: write + id-token: write + +concurrency: + group: "pages" + cancel-in-progress: false + +jobs: + deploy: + runs-on: ubuntu-latest + environment: + name: github-pages + url: ${{ steps.deployment.outputs.page_url }} + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Setup Pages + uses: actions/configure-pages@v5 + + - name: Upload artifact + uses: actions/upload-pages-artifact@v4 + with: + path: "website" + + - name: Deploy to GitHub Pages + id: deployment + uses: actions/deploy-pages@v4 diff --git a/.github/workflows/publish-pypi-auto.yml b/.github/workflows/publish-pypi-auto.yml new file mode 100644 index 0000000..f5c650e --- /dev/null +++ b/.github/workflows/publish-pypi-auto.yml @@ -0,0 +1,36 @@ +name: Publish PyPI (Auto) + +on: + push: + tags: + - "v*" + release: + types: [published] + +jobs: + publish: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Set up Python + uses: actions/setup-python@v5 + with: + python-version: "3.11" + + - name: Install build tooling + run: | + python -m pip install --upgrade pip + python -m pip install build twine + + - name: Build package + run: python -m build + + - name: Publish to PyPI + env: + TWINE_USERNAME: __token__ + TWINE_PASSWORD: ${{ secrets.PYPI_API_TOKEN }} + run: | + python -m twine upload dist/* --skip-existing --verbose diff --git a/.github/workflows/update-hall-of-fame.yml b/.github/workflows/update-hall-of-fame.yml new file mode 100644 index 0000000..3fbc815 --- /dev/null +++ b/.github/workflows/update-hall-of-fame.yml @@ -0,0 +1,60 @@ +name: Update Hall of Fame + +on: + push: + branches: ["main"] + paths-ignore: + - "website/data/contributors.json" + schedule: + - cron: "0 2 * * *" + workflow_dispatch: + +permissions: + contents: write + +jobs: + update-contributors: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v5 + + - name: Build contributor data from GitHub API + uses: actions/github-script@v7 + with: + script: | + const owner = context.repo.owner; + const repo = context.repo.repo; + const perPage = 100; + const contributors = await github.paginate( + github.rest.repos.listContributors, + { owner, repo, per_page: perPage } + ); + + const mapped = contributors + .filter(c => c.type === 'User') + .map(c => ({ + login: c.login, + profile: c.html_url, + contributions: c.contributions + })) + .sort((a, b) => b.contributions - a.contributions); + + const fs = require('fs'); + fs.writeFileSync( + 'website/data/contributors.json', + JSON.stringify(mapped, null, 2) + '\n' + ); + + - name: Commit updates + run: | + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + if git diff --quiet; then + echo "No contributor changes" + else + git add website/data/contributors.json + git commit -m "chore: update hall of fame contributors" + git push + fi diff --git a/README.md b/README.md index f4db39a..cdbbcda 100644 --- a/README.md +++ b/README.md @@ -39,6 +39,14 @@ ExecuTrace is a Python library and CLI tool that captures developer workflows an - Document complex workflows reliably - Ensure consistent deployments +## Documentation Website + +The full open source docs website (retro 70s style) lives in `website/` and can be deployed with GitHub Pages. + +- Source: `website/index.html` +- Hall of Fame data: `website/data/contributors.json` +- Security Hall of Fame data: `website/data/security_hof.json` + --- ## Installation @@ -79,3 +87,8 @@ exectrace replay my-workflow --explain MIT License - See [LICENSE](LICENSE) for details. +## Security + +- Policy: [SECURITY.md](SECURITY.md) +- Advisory process: [SECURITY_ADVISORY.md](SECURITY_ADVISORY.md) + diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..fdfff80 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,30 @@ +# Security Policy + +## Supported Versions + +We currently support security updates for the latest stable release on PyPI: + +- `exectrace-workflow` latest version + +## Reporting a Vulnerability + +Please do **not** open a public issue for security bugs. + +Use one of these methods: + +1. GitHub Security Advisories (preferred): + - Go to Security tab in the repository + - Click Advisories + - Start a private vulnerability report +2. If advisories are unavailable, open a private report via repository maintainers. + +## Disclosure Timeline + +1. We acknowledge reports within 72 hours. +2. We validate and reproduce the issue. +3. We prepare a fix and release patch. +4. We publish an advisory with credit (if requested). + +## Hall of Fame + +Responsible reporters are credited on the project website under Security Hall of Fame after a fix is shipped. diff --git a/SECURITY_ADVISORY.md b/SECURITY_ADVISORY.md new file mode 100644 index 0000000..2fc01ff --- /dev/null +++ b/SECURITY_ADVISORY.md @@ -0,0 +1,36 @@ +# Security Advisory Process + +This document defines how ExecuTrace handles vulnerability advisories. + +## Advisory Workflow + +1. Receive private report +2. Triaging and severity assessment +3. Patch development and review +4. Coordinated release +5. Public advisory publication and attribution + +## Severity Guide + +- Critical: Remote execution, full compromise +- High: Privilege escalation, data exposure +- Medium: Significant abuse with constraints +- Low: Limited impact + +## Attribution + +Contributors and researchers who responsibly disclose verified vulnerabilities are added to: + +- `website/data/security_hof.json` +- website Security Hall of Fame section + +## Advisory Template + +- Title +- Affected versions +- CVSS/severity +- Technical summary +- Reproduction +- Mitigation +- Fixed version +- Credits diff --git a/website/assets/app.js b/website/assets/app.js new file mode 100644 index 0000000..79db186 --- /dev/null +++ b/website/assets/app.js @@ -0,0 +1,43 @@ +async function readJson(path) { + const res = await fetch(path); + if (!res.ok) { + return []; + } + return res.json(); +} + +function renderTable(containerId, headers, rows) { + const container = document.getElementById(containerId); + if (!container) return; + + if (!rows.length) { + container.innerHTML = "

No entries yet.

"; + return; + } + + const head = headers.map((h) => `${h}`).join(""); + const body = rows.map((row) => `${row.map((c) => `${c}`).join("")}`).join(""); + + container.innerHTML = `${head}${body}
`; +} + +async function init() { + const contributors = await readJson("data/contributors.json"); + const security = await readJson("data/security_hof.json"); + + const contributorRows = contributors.map((c) => [ + `${c.login}`, + String(c.contributions), + ]); + + const securityRows = security.map((s) => [ + s.name, + s.issue, + s.reported, + ]); + + renderTable("contributors", ["Contributor", "Commits"], contributorRows); + renderTable("security-hof", ["Researcher", "Issue", "Reported"], securityRows); +} + +init(); diff --git a/website/assets/style.css b/website/assets/style.css new file mode 100644 index 0000000..ff88033 --- /dev/null +++ b/website/assets/style.css @@ -0,0 +1,118 @@ +:root { + --bg: #15100d; + --panel: #1f1712; + --text: #ffd79a; + --accent: #ff8f3f; + --line: #6e4b2a; + --glow: #ffb36b; +} + +* { + box-sizing: border-box; +} + +body { + margin: 0; + font-family: "Courier New", Courier, monospace; + background: radial-gradient(circle at top, #2a1b12 0%, var(--bg) 45%, #0d0b0a 100%); + color: var(--text); + line-height: 1.5; +} + +.grain { + position: fixed; + inset: 0; + pointer-events: none; + opacity: 0.08; + background-image: repeating-linear-gradient(0deg, rgba(255, 255, 255, 0.08) 0, rgba(255, 255, 255, 0.08) 1px, transparent 1px, transparent 2px); +} + +.hero { + text-align: center; + padding: 3rem 1rem 2rem; + border-bottom: 2px solid var(--line); + box-shadow: 0 0 30px rgba(255, 143, 63, 0.2); +} + +.hero h1 { + margin: 0.5rem 0; + font-size: clamp(2rem, 8vw, 5rem); + letter-spacing: 0.2rem; + text-shadow: 0 0 12px var(--glow); +} + +.subtitle, +.mono { + margin: 0.5rem 0; +} + +.hero-actions { + margin-top: 1rem; +} + +.hero-actions a { + color: var(--accent); + margin: 0 0.6rem; + border: 1px solid var(--line); + padding: 0.4rem 0.7rem; + text-decoration: none; + display: inline-block; +} + +main { + width: min(1000px, 92%); + margin: 1.5rem auto 3rem; +} + +section { + margin: 1.2rem 0; + background: var(--panel); + border: 1px solid var(--line); + padding: 1rem; +} + +h2 { + margin-top: 0; + color: var(--accent); +} + +pre { + background: #120e0b; + border: 1px solid var(--line); + padding: 0.8rem; + overflow-x: auto; +} + +.grid { + display: grid; + grid-template-columns: repeat(auto-fit, minmax(220px, 1fr)); + gap: 1rem; +} + +.table { + border: 1px solid var(--line); + background: #120e0b; + padding: 0.8rem; +} + +.table table { + width: 100%; + border-collapse: collapse; +} + +.table th, +.table td { + text-align: left; + padding: 0.45rem; + border-bottom: 1px dashed var(--line); +} + +a { + color: #ffc66d; +} + +footer { + text-align: center; + padding: 1rem; + border-top: 1px solid var(--line); +} diff --git a/website/data/contributors.json b/website/data/contributors.json new file mode 100644 index 0000000..fe51488 --- /dev/null +++ b/website/data/contributors.json @@ -0,0 +1 @@ +[] diff --git a/website/data/security_hof.json b/website/data/security_hof.json new file mode 100644 index 0000000..be836ac --- /dev/null +++ b/website/data/security_hof.json @@ -0,0 +1,7 @@ +[ + { + "name": "Reserved", + "issue": "Waiting for first responsible disclosure", + "reported": "-" + } +] diff --git a/website/index.html b/website/index.html new file mode 100644 index 0000000..10f0d65 --- /dev/null +++ b/website/index.html @@ -0,0 +1,103 @@ + + + + + + + ExecuTrace // Open Source Docs + + + +
+
+

EST. 2026 // OPEN SOURCE DEV WORKFLOW TOOLKIT

+

EXECUTRACE

+

Record terminal workflows. Replay with confidence.

+
+ PyPI Package + GitHub Repo +
+
+ +
+
+

What Is ExecuTrace?

+

+ ExecuTrace is a Python CLI and library for recording command history and file system changes, + then replaying those workflows in reliable, repeatable modes. +

+
+ +
+

Install

+ 
pip install exectrace-workflow
+exectrace --help
+
+ +
+

Core Commands

+
+
+

Record

+ 
exectrace record my-workflow
+# run commands
+exectrace stop
+
+
+

Replay

+ 
exectrace replay my-workflow --explain
+exectrace replay my-workflow --dry-run
+exectrace replay my-workflow --smart
+
+
+

Manage

+ 
exectrace list
+exectrace edit my-workflow
+exectrace delete my-workflow
+
+
+
+ +
+

Architecture Snapshot

+ +
+ +
+

Automatic Open Source Credits

+

+ Contributors are updated automatically by GitHub workflow and displayed below. +

+
+
+ +
+

Security Hall of Fame

+

+ Researchers who responsibly disclose vulnerabilities are listed here after verification. +

+
+
+ +
+

Security and Advisory Process

+ +
+
+ + + + + +