diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..ef7cc90 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,20 @@ +# Pull Request + +## Summary + + +## Type of change +- [ ] Feature +- [ ] Bug fix +- [ ] Security fix +- [ ] Docs / chore + +## Security checklist +- [ ] No secrets, tokens, API keys, or real data added to the repo +- [ ] New dependencies reviewed (license + known CVEs) +- [ ] Input validation / output encoding considered for any new user input +- [ ] CodeQL and Security Scan workflows pass +- [ ] Threat model / docs updated if behavior or trust boundaries changed + +## Testing + diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 0000000..a70e840 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,27 @@ +# Dependabot keeps dependencies patched and surfaces known-vulnerable versions. +# Docs: https://docs.github.com/code-security/dependabot +version: 2 +updates: + # Python dependencies (pip / requirements.txt / pyproject) + - package-ecosystem: "pip" + directory: "/" + schedule: + interval: "weekly" + open-pull-requests-limit: 10 + labels: + - "dependencies" + - "security" + commit-message: + prefix: "deps" + include: "scope" + + # GitHub Actions used in workflows (pin & patch action versions) + - package-ecosystem: "github-actions" + directory: "/" + schedule: + interval: "weekly" + labels: + - "dependencies" + - "ci" + commit-message: + prefix: "ci" diff --git a/.github/workflows/codeql.yml b/.github/workflows/codeql.yml new file mode 100644 index 0000000..0423021 --- /dev/null +++ b/.github/workflows/codeql.yml @@ -0,0 +1,43 @@ +# CodeQL static analysis (SAST). Results appear in the repo Security tab. +# Docs: https://docs.github.com/code-security/code-scanning +name: CodeQL + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: "27 4 * * 1" # weekly, Monday 04:27 UTC + +permissions: + contents: read + security-events: write # required to upload results to code scanning + +jobs: + analyze: + name: Analyze (${{ matrix.language }}) + runs-on: ubuntu-latest + strategy: + fail-fast: false + matrix: + # Add/remove languages to match the repo. CodeQL supports: + # python, javascript-typescript, java-kotlin, go, ruby, csharp, c-cpp, swift + language: [ "javascript-typescript" ] + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Initialize CodeQL + uses: github/codeql-action/init@v3 + with: + languages: ${{ matrix.language }} + queries: security-extended + + - name: Autobuild + uses: github/codeql-action/autobuild@v3 + + - name: Perform CodeQL Analysis + uses: github/codeql-action/analyze@v3 + with: + category: "/language:${{ matrix.language }}" diff --git a/.github/workflows/security-scan.yml b/.github/workflows/security-scan.yml new file mode 100644 index 0000000..a7eb602 --- /dev/null +++ b/.github/workflows/security-scan.yml @@ -0,0 +1,74 @@ +# Unified security scan: secret detection (gitleaks), dependency/vuln + IaC +# scanning (Trivy), and SBOM generation (Syft). SARIF results upload to the +# repo Security tab. Designed to run on push, PR, and weekly. +name: Security Scan + +on: + push: + branches: [ "main" ] + pull_request: + branches: [ "main" ] + schedule: + - cron: "27 5 * * 1" # weekly, Monday 05:27 UTC + +permissions: + contents: read + security-events: write + +jobs: + secret-scan: + name: Secret scan (gitleaks) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + with: + fetch-depth: 0 # full history so gitleaks can scan past commits + - name: Run gitleaks + uses: gitleaks/gitleaks-action@v2 + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + # GITLEAKS_ENABLE_UPLOAD_ARTIFACT: "true" + + dependency-and-iac-scan: + name: Trivy (deps + secrets + misconfig) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run Trivy filesystem scan + uses: aquasecurity/trivy-action@0.35.0 + with: + scan-type: "fs" + scan-ref: "." + format: "sarif" + output: "trivy-results.sarif" + severity: "CRITICAL,HIGH" + ignore-unfixed: true + + - name: Upload Trivy results to Security tab + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: "trivy-results.sarif" + + sbom: + name: Generate SBOM (Syft) + runs-on: ubuntu-latest + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Generate SBOM (SPDX + CycloneDX) + uses: anchore/sbom-action@v0 + with: + format: spdx-json + output-file: sbom.spdx.json + + - name: Upload SBOM artifact + uses: actions/upload-artifact@v4 + with: + name: sbom + path: sbom.spdx.json + retention-days: 90 diff --git a/.gitignore b/.gitignore index 436cb4c..3842166 100644 --- a/.gitignore +++ b/.gitignore @@ -3,4 +3,62 @@ venv/ __pycache__/ *.pyc -*.log \ No newline at end of file +*.log +# ---- FoundryGuard fix-pack additions ---- +# ---- Secrets & local config (NEVER commit) ---- +.env +.env.* +*.env +*.pem +*.key +*.pfx +*.p12 +secrets.* +credentials.* +*_secret* +*apikey* +*api_key* + +# ---- Runtime / generated security artifacts ---- +# These often contain real hostnames, findings, or tokens. Ship *.sample.json instead. +audit_log.json +findings.json +assets.json +discovery_results.json +redteam_results.txt +*.log + +# ---- Python ---- +__pycache__/ +*.py[cod] +*$py.class +.Python +build/ +dist/ +*.egg-info/ +.eggs/ +.venv/ +venv/ +env/ +ENV/ +.pytest_cache/ +.mypy_cache/ +.ruff_cache/ +.coverage +htmlcov/ + +# ---- Node (for any JS tooling) ---- +node_modules/ +npm-debug.log* + +# ---- Editors / OS ---- +.vscode/ +.idea/ +.DS_Store +Thumbs.db + +# ---- SBOM / scan outputs (regenerated in CI) ---- +sbom.spdx.json +sbom.cdx.json +trivy-results.sarif +gitleaks-report.json diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..51027d3 --- /dev/null +++ b/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Anthony N. Saunders + +Permission is hereby granted, free of charge, to any person obtaining a copy +of this software and associated documentation files (the "Software"), to deal +in the Software without restriction, including without limitation the rights +to use, copy, modify, merge, publish, distribute, sublicense, and/or sell +copies of the Software, and to permit persons to whom the Software is +furnished to do so, subject to the following conditions: + +The above copyright notice and this permission notice shall be included in all +copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR +IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, +FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE +AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER +LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, +OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE +SOFTWARE. diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..5d5e936 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,58 @@ +# Security Policy + +## Purpose & Status + +This repository is a **security research / portfolio project**. It demonstrates +security engineering concepts and is **not production-hardened**. Do not deploy +it as-is to handle real production data, secrets, or traffic without an +independent security review. + +## Supported Versions + +Only the latest commit on the default branch is maintained. + +| Version | Supported | +| ---------------- | ------------------ | +| `main` (latest) | :white_check_mark: | +| older commits | :x: | + +## Reporting a Vulnerability + +If you discover a security issue in this project, please report it privately. + +- **Preferred:** Open a [GitHub Security Advisory](../../security/advisories/new) + (Security tab → "Report a vulnerability"). This keeps the report private until + a fix is ready. +- **Email:** asaunders@dmcslabs.com + +Please include: + +1. A description of the issue and its impact. +2. Steps to reproduce (proof-of-concept where possible). +3. Affected files, endpoints, or components. +4. Any suggested remediation. + +**Please do not** open a public issue for security-sensitive reports. + +## Response Targets + +| Stage | Target | +| --------------------- | ----------------- | +| Acknowledge report | 3 business days | +| Triage & severity | 7 business days | +| Fix or mitigation plan| 30 days (severity-dependent) | + +Severity is assessed using CVSS v3.1. Critical/High issues are prioritized. + +## Scope + +In scope: source code in this repository. +Out of scope: third-party dependencies (report upstream), social engineering, +and any deployment a user stands up themselves. + +## Safe Harbor + +Good-faith security research conducted in accordance with this policy is +welcome. Do not access data that is not yours, degrade service for others, or +violate any law. Acting in good faith under this policy, you will not be pursued +for the research.