diff --git a/.github/CODEOWNERS b/.github/CODEOWNERS new file mode 100644 index 00000000..5f69c379 --- /dev/null +++ b/.github/CODEOWNERS @@ -0,0 +1,16 @@ +# This file defines code owners for the repository. +# It assigns the default owner for all files to @HardMax71. +# Later, specific paths can be assigned to different teams or individuals. + +# Default owner for everything +* @HardMax71 + +# Backend +backend/ @HardMax71 + +# Frontend +frontend/ @HardMax71 + +# DevOps / Helm / CI +helm/ @HardMax71 +.github/ @HardMax71 diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 00000000..4b575be2 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,86 @@ +name: Bug Report +description: Report unexpected behavior or errors +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for taking the time to report a bug! Please fill out the sections below. + + - type: textarea + id: description + attributes: + label: Bug Description + description: A clear and concise description of what the bug is. + placeholder: What happened? + validations: + required: true + + - type: textarea + id: reproduction + attributes: + label: Steps to Reproduce + description: Steps to reproduce the behavior. + placeholder: | + 1. Go to '...' + 2. Click on '...' + 3. See error + validations: + required: true + + - type: textarea + id: expected + attributes: + label: Expected Behavior + description: What you expected to happen. + validations: + required: true + + - type: dropdown + id: component + attributes: + label: Component + description: Which part of the system is affected? + options: + - Frontend (UI) + - Backend API + - Execution (K8s pods) + - Workers (Coordinator, DLQ, etc.) + - SSE / Real-time updates + - Authentication + - Other + validations: + required: true + + - type: textarea + id: environment + attributes: + label: Environment + description: Please provide relevant environment details. + placeholder: | + - OS: [e.g., Ubuntu 22.04, macOS 14] + - Browser: [e.g., Chrome 120, Firefox 121] + - Deployment: [e.g., local dev, production] + - Python version: [e.g., 3.12] + validations: + required: false + + - type: textarea + id: logs + attributes: + label: Relevant Logs + description: Include any error messages or logs (use code blocks). + render: shell + validations: + required: false + + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true + - label: I have included steps to reproduce the issue + required: true diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..801dd3f4 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: Documentation + url: https://hardmax71.github.io/Integr8sCode/ + about: Check the documentation for guides and reference material + - name: Discussions + url: https://github.com/HardMax71/Integr8sCode/discussions + about: Ask questions and discuss ideas diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 00000000..319c796f --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,66 @@ +name: Feature Request +description: Suggest a new feature or enhancement +title: "[Feature]: " +labels: ["enhancement"] +body: + - type: markdown + attributes: + value: | + Thanks for suggesting a feature! Please describe what you'd like to see. + + - type: textarea + id: problem + attributes: + label: Problem Statement + description: What problem does this feature solve? Is it related to a frustration? + placeholder: I'm always frustrated when... + validations: + required: true + + - type: textarea + id: solution + attributes: + label: Proposed Solution + description: Describe the solution you'd like. + validations: + required: true + + - type: textarea + id: alternatives + attributes: + label: Alternatives Considered + description: Any alternative solutions or features you've considered? + validations: + required: false + + - type: dropdown + id: component + attributes: + label: Component + description: Which part of the system would this affect? + options: + - Frontend (UI) + - Backend API + - Execution (K8s pods) + - Workers + - Documentation + - DevOps / CI/CD + - Other + validations: + required: true + + - type: textarea + id: context + attributes: + label: Additional Context + description: Add any other context, mockups, or screenshots. + validations: + required: false + + - type: checkboxes + id: checklist + attributes: + label: Checklist + options: + - label: I have searched existing issues to ensure this is not a duplicate + required: true diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 00000000..28ad1e4d --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,50 @@ +## Summary + + + +Fixes # + +## Changes + + + +- +- +- + +## Type of Change + + + +- [ ] Bug fix (non-breaking change that fixes an issue) +- [ ] New feature (non-breaking change that adds functionality) +- [ ] Breaking change (fix or feature that would cause existing functionality to change) +- [ ] Documentation update +- [ ] Refactoring (no functional changes) +- [ ] CI/CD or tooling changes + +## Test Plan + + + +- [ ] Unit tests pass (`uv run pytest`) +- [ ] E2E tests pass (`npx playwright test`) +- [ ] Manual testing performed + +**Manual test steps:** + +1. +2. +3. + +## Checklist + +- [ ] My code follows the project's style guidelines +- [ ] I have run `pre-commit run --all-files` and all checks pass +- [ ] I have added tests that prove my fix/feature works +- [ ] I have updated documentation if needed +- [ ] My changes don't introduce new warnings + +## Screenshots (if applicable) + + diff --git a/.github/workflows/sbom-compliance.yml b/.github/workflows/sbom-compliance.yml new file mode 100644 index 00000000..858a8106 --- /dev/null +++ b/.github/workflows/sbom-compliance.yml @@ -0,0 +1,63 @@ +name: SBOM & Supply Chain Security + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + schedule: + - cron: '0 0 * * 0' # Run weekly on Sundays + +permissions: + contents: read + security-events: write + +jobs: + sbom-analysis: + name: Generate & Scan SBOMs + runs-on: ubuntu-latest + strategy: + matrix: + component: [backend, frontend] + include: + - component: backend + path: ./backend + type: python + - component: frontend + path: ./frontend + type: javascript + + steps: + - name: Checkout Code + uses: actions/checkout@v4 + + - name: Generate SBOM (${{ matrix.component }}) + uses: anchore/sbom-action@v0 + id: sbom + with: + path: ${{ matrix.path }} + format: spdx-json + output-file: ${{ matrix.component }}-sbom.spdx.json + upload-artifact: false + + - name: Scan SBOM for Vulnerabilities + uses: anchore/scan-action@v6 + id: scan + with: + sbom: ${{ matrix.component }}-sbom.spdx.json + fail-build: false # Don't block builds yet, just report + severity-cutoff: high + + - name: Upload SBOM Artifact + uses: actions/upload-artifact@v4 + with: + name: ${{ matrix.component }}-sbom + path: ${{ matrix.component }}-sbom.spdx.json + retention-days: 5 + + - name: Upload Vulnerability Report + uses: github/codeql-action/upload-sarif@v3 + if: always() + with: + sarif_file: ${{ steps.scan.outputs.sarif }} + category: ${{ matrix.component }}-dependencies diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 00000000..984dfc83 --- /dev/null +++ b/.pre-commit-config.yaml @@ -0,0 +1,23 @@ +# Pre-commit hooks configuration +# Install: uv tool install pre-commit && pre-commit install +# Run manually: pre-commit run --all-files + +repos: + # Local hooks using uv run to match CI exactly + - repo: local + hooks: + # Ruff - matches CI: cd backend && uv run ruff check . --config pyproject.toml + - id: ruff-backend + name: ruff check (backend) + entry: bash -c 'cd backend && uv run ruff check . --config pyproject.toml' + language: system + files: ^backend/.*\.py$ + pass_filenames: false + + # MyPy - matches CI: cd backend && uv run mypy --config-file pyproject.toml --strict . + - id: mypy-backend + name: mypy --strict (backend) + entry: bash -c 'cd backend && uv run mypy --config-file pyproject.toml --strict .' + language: system + files: ^backend/.*\.py$ + pass_filenames: false diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 00000000..f32b3111 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,45 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We pledge to make our community welcoming, safe, and equitable for all. We are committed to fostering an environment that respects and promotes the dignity, rights, and contributions of all individuals, regardless of characteristics including race, ethnicity, caste, color, age, physical characteristics, neurodiversity, disability, sex or gender, gender identity or expression, sexual orientation, language, philosophy or religion, national or social origin, socio-economic position, level of education, or other status. The same privileges of participation are extended to everyone who participates in good faith and in accordance with this Covenant. + +## Encouraged Behaviors + +While acknowledging differences in social norms, we all strive to meet our community's expectations for positive behavior. We also understand that our words and actions may be interpreted differently than we intend based on culture, background, or native language. With these considerations in mind, we agree to behave mindfully toward each other and act in ways that center our shared values, including: + +* Respecting the purpose of our community, our activities, and our ways of gathering. +* Engaging kindly and honestly with others. +* Respecting different viewpoints and experiences. +* Taking responsibility for our actions and contributions. +* Gracefully giving and accepting constructive feedback. +* Committing to repairing harm when it occurs. +* Behaving in other ways that promote and sustain the well-being of our community. + +## Restricted Behaviors + +We agree to restrict the following behaviors in our community. Instances, threats, and promotion of these behaviors are violations of this Code of Conduct. + +* **Harassment.** Violating explicitly expressed boundaries or engaging in unnecessary personal attention after any clear request to stop. +* **Character attacks.** Making insulting, demeaning, or pejorative comments directed at a community member or group of people. +* **Stereotyping or discrimination.** Characterizing anyone's personality or behavior on the basis of immutable identities or traits. +* **Sexualization.** Using sexualized language or imagery, or engaging in unwelcome sexual attention or advances. +* **Violating confidentiality.** Publishing others' private information, such as a physical or email address, without their explicit permission. +* **Endangerment.** Threatening or inciting violence, or promoting self-harm. +* Behaving in other ways that threaten the well-being of our community. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when an individual is officially representing the community in public or other spaces. Examples of representing our community include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the community leaders responsible for enforcement at . All complaints will be reviewed and investigated promptly and fairly. + +All community leaders are obligated to respect the privacy and security of the reporter of any incident. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 3.0, available at [Contributor Covenant](https://www.contributor-covenant.org/version/3/0/). + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..52af00c7 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,138 @@ +# Contributing to Integr8sCode + +Thank you for your interest in contributing! This guide will help you get started. + +## Development Setup + +### Prerequisites + +- Python 3.12+ +- Node.js 20+ +- Docker & Docker Compose +- [uv](https://docs.astral.sh/uv/) (Python package manager) +- k3s (for Kubernetes integration) + +### Clone and Setup + +```bash +git clone https://github.com/HardMax71/Integr8sCode.git +cd Integr8sCode + +# Install pre-commit hooks (required before submitting PRs) +uv tool install pre-commit +pre-commit install + +# Start the development environment +./deploy.sh dev +``` + +### Pre-commit Hooks + +**Before submitting any PR**, ensure pre-commit hooks are installed. They run automatically on `git commit` and check: + +- **ruff**: Python linting (style, imports, potential bugs) +- **mypy --strict**: Static type checking + +Run manually on all files: + +```bash +pre-commit run --all-files +``` + +If hooks fail, fix the issues before committing. The same checks run in CI, so local failures will also fail the pipeline. + +### Backend Development + +```bash +cd backend + +# Install dependencies +uv sync + +# Run linting +uv run ruff check . --config pyproject.toml + +# Run type checking +uv run mypy --config-file pyproject.toml --strict . + +# Run tests +uv run pytest +``` + +### Frontend Development + +```bash +cd frontend + +# Install dependencies +npm install + +# Run dev server +npm run dev + +# Run E2E tests +npx playwright test +``` + +## Code Style + +### Python (Backend) + +- Follow PEP 8 with 120 character line limit +- Use type hints for all function signatures +- Ruff handles import sorting and style enforcement +- MyPy strict mode enforces complete type coverage + +### TypeScript/Svelte (Frontend) + +- Use TypeScript for all new code +- Follow existing component patterns +- Use Svelte 5 runes syntax + +## Pull Request Process + +1. **Create a feature branch** from `main`: + ```bash + git checkout -b feature/your-feature-name + ``` + +2. **Make your changes** with clear, atomic commits + +3. **Ensure all checks pass**: + ```bash + pre-commit run --all-files + cd backend && uv run pytest + cd frontend && npx playwright test + ``` + +4. **Push and create a PR** against `main` + +5. **Fill out the PR template** with: + - Summary of changes + - Test plan + - Any breaking changes + +## Commit Messages + +Use clear, descriptive commit messages: + +``` +feat: add user notification preferences +fix: resolve race condition in execution coordinator +docs: update deployment guide for k3s setup +refactor: extract common validation logic +test: add integration tests for DLQ processor +``` + +## Reporting Issues + +Use GitHub Issues with the provided templates: + +- **Bug Report**: For unexpected behavior or errors +- **Feature Request**: For new functionality suggestions + +Include reproduction steps, environment details, and relevant logs. + +## Questions? + +Open a GitHub Discussion or reach out via issues. diff --git a/SUPPORT.md b/SUPPORT.md new file mode 100644 index 00000000..24e84650 --- /dev/null +++ b/SUPPORT.md @@ -0,0 +1,27 @@ +# Support + +Thank you for using Integr8sCode! We want to ensure you have a smooth experience. This document outlines how to get help, report issues, and suggest improvements. + +## Where to Get Help + +### 1. Documentation +Before asking a question, please check our project documentation (located in the `docs/` directory or our documentation site). It covers architecture, deployment, and configuration details. + +### 2. GitHub Discussions +For general questions, best practices, or architectural discussions that aren't bugs, please use [GitHub Discussions](https://github.com/HardMax71/Integr8sCode/discussions). + +### 3. GitHub Issues +If you encounter a bug or have a specific feature request, please verify it hasn't already been reported, then [open an issue](https://github.com/HardMax71/Integr8sCode/issues). + +* **Bug Reports:** Please use the "Bug Report" template and provide reproduction steps. +* **Feature Requests:** Please use the "Feature Request" template and describe the use case clearly. + +## Professional Support / Privacy + +For privacy-related inquiries, GDPR requests, or professional support queries, please contact us directly via email: + +* **Email:** [max.azatian@gmail.com](mailto:max.azatian@gmail.com) + +## Community Guidelines + +When interacting with the community, please adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). We strive to maintain a welcoming and respectful environment for everyone. diff --git a/docs/SECURITY.md b/docs/SECURITY.md new file mode 100644 index 00000000..cbac2e60 --- /dev/null +++ b/docs/SECURITY.md @@ -0,0 +1,62 @@ +# Security Policy + +Integr8sCode takes the security of our software and our users' data seriously. We are committed to ensuring a secure +environment and following best practices for vulnerability management and disclosure. + +## Supported Versions + +We currently support security updates for the following versions of Integr8sCode: + +| Version | Supported | +|----------------|--------------------| +| `main` | :white_check_mark: | +| Latest Release | :white_check_mark: | + +If you are running an older version, we strongly recommend upgrading to the latest release to ensure you have the most +recent security patches. + +## Reporting a Vulnerability + +If you discover a security vulnerability within Integr8sCode, please **DO NOT** create a public GitHub issue. Instead, +please report it privately to our security team. + +### How to Report + +1. **Email:** Send a detailed report to . +2. **Details:** Please include as much information as possible: + * Type of vulnerability (e.g., XSS, SQL Injection, RCE). + * Full path or URL where the vulnerability occurs. + * Step-by-step instructions to reproduce the issue. + * Proof of concept (PoC) code or screenshots, if available. + * Any specific configuration required to reproduce the issue. + +### Our Response Process + +1. **Acknowledgment:** We will acknowledge receipt of your report within 48 hours. +2. **Assessment:** We will investigate the issue to confirm its validity and impact. +3. **Resolution:** If confirmed, we will work on a patch. We will keep you updated on our progress. +4. **Disclosure:** Once a fix is released, we will publicly disclose the vulnerability (with your permission, crediting + you for the discovery). + +## Security Measures + +We employ several automated tools and practices to maintain the security of our codebase: + +* **Static Application Security Testing (SAST):** We use **Bandit** to scan our Python backend code for common security + issues. +* **Dependency Management:** We use **Dependabot** to automatically monitor and update vulnerable dependencies in our + `package.json`, `pyproject.toml`, and Docker files. +* **Container Security:** We follow best practices for containerization, including using minimal base images and + non-root users where possible. +* **Secrets Management:** We do not commit secrets to the repository. Please ensure `.env` files and other secrets are + properly managed in your deployment environment. + +## Software Bill of Materials (SBOM) + +We strive to maintain transparency regarding our dependencies. You can inspect our direct dependencies in: + +* `backend/pyproject.toml` (Python) +* `frontend/package.json` (Node.js/Svelte) +* `helm/integr8scode/Chart.yaml` (Kubernetes/Helm) + +Thank you for helping keep Integr8sCode safe! diff --git a/docs/index.md b/docs/index.md index 878d7fde..c11db4ed 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,5 +1,6 @@ # Integr8sCode +[![SBOM & Supply Chain Security](https://github.com/HardMax71/Integr8sCode/actions/workflows/sbom-compliance.yml/badge.svg)](https://github.com/HardMax71/Integr8sCode/actions/workflows/sbom-compliance.yml) [GitHub :material-github:](https://github.com/HardMax71/Integr8sCode){ .md-button } [Live Demo :material-play:](https://app.integr8scode.cc/){ .md-button .md-button--primary } @@ -80,6 +81,7 @@ For detailed architecture diagrams, see the [Architecture](architecture/overview | Non-root execution | Dropped capabilities, no privilege escalation| | Filesystem | Read-only root filesystem | | Kubernetes API | No service account token mounted | +| Supply Chain (SBOM) | [Weekly Scans & Artifacts](https://github.com/HardMax71/Integr8sCode/actions/workflows/sbom-compliance.yml) | ## Documentation @@ -121,6 +123,12 @@ For detailed architecture diagrams, see the [Architecture](architecture/overview Frontend routing and components +- :material-github: **[Contributing](https://github.com/HardMax71/Integr8sCode/blob/main/CONTRIBUTING.md)** + + --- + + Development setup, pre-commit hooks, and PR guidelines + ## Sample code diff --git a/mkdocs.yml b/mkdocs.yml index 5140f5e5..3b29cd08 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -163,7 +163,9 @@ nav: - Grafana Integration: operations/grafana-integration.md - Admin API: operations/admin-api.md - - Network Isolation: security/policies.md + - Security: + - Policy & SBOM: SECURITY.md + - Network Isolation: security/policies.md - Frontend: - Routing: frontend/routing.md