From 2189d09bd9fcb6e9ba5e7a7bdd623cf9f8d1efc8 Mon Sep 17 00:00:00 2001 From: Mariano Ortega Date: Tue, 16 Jun 2026 00:20:20 +0200 Subject: [PATCH] chore: add open-source publication scaffolding Prepare the repository for a professional public release: - LICENSE: MIT for source code (dual-licensing note; ontology stays CC BY 4.0) - CITATION.cff for academic citation - CONTRIBUTING.md, CODE_OF_CONDUCT.md (Contributor Covenant 2.1), SECURITY.md - .github/: issue templates (bug/feature), PR template, CI workflow - CI: frontend build + Python syntax/lint checks - README: MIT + CI badges, dual-license section - LICENSES: align project license section with MIT Co-Authored-By: Claude Opus 4.8 (1M context) --- .github/ISSUE_TEMPLATE/bug_report.yml | 64 +++++++++++++++ .github/ISSUE_TEMPLATE/config.yml | 8 ++ .github/ISSUE_TEMPLATE/feature_request.yml | 43 ++++++++++ .github/PULL_REQUEST_TEMPLATE.md | 30 +++++++ .github/workflows/ci.yml | 49 ++++++++++++ CITATION.cff | 32 ++++++++ CODE_OF_CONDUCT.md | 57 ++++++++++++++ CONTRIBUTING.md | 92 ++++++++++++++++++++++ LICENSE | 36 +++++++++ LICENSES | 5 +- README.md | 13 ++- SECURITY.md | 47 +++++++++++ 12 files changed, 471 insertions(+), 5 deletions(-) create mode 100644 .github/ISSUE_TEMPLATE/bug_report.yml create mode 100644 .github/ISSUE_TEMPLATE/config.yml create mode 100644 .github/ISSUE_TEMPLATE/feature_request.yml create mode 100644 .github/PULL_REQUEST_TEMPLATE.md create mode 100644 .github/workflows/ci.yml create mode 100644 CITATION.cff create mode 100644 CODE_OF_CONDUCT.md create mode 100644 CONTRIBUTING.md create mode 100644 LICENSE create mode 100644 SECURITY.md diff --git a/.github/ISSUE_TEMPLATE/bug_report.yml b/.github/ISSUE_TEMPLATE/bug_report.yml new file mode 100644 index 0000000..e17e2a1 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/bug_report.yml @@ -0,0 +1,64 @@ +name: 🐛 Bug report +description: Report a problem with SERAMIS +title: "[Bug]: " +labels: ["bug", "triage"] +body: + - type: markdown + attributes: + value: | + Thanks for reporting a bug! Please fill in as much detail as possible. + - type: textarea + id: description + attributes: + label: Description + description: A clear and concise description of what the bug is. + validations: + required: true + - type: dropdown + id: component + attributes: + label: Affected component + options: + - Frontend (React UI) + - Backend (FastAPI) + - Reasoner service + - Forensic agent + - MCP SPARQL server + - Ontology / semantic resources + - Docker / deployment + - Other / not sure + validations: + required: true + - type: textarea + id: reproduce + attributes: + label: Steps to reproduce + description: How can we reproduce the behavior? + placeholder: | + 1. Go to '...' + 2. Run '...' + 3. See error + validations: + required: true + - type: textarea + id: expected + attributes: + label: Expected behavior + validations: + required: true + - type: textarea + id: logs + attributes: + label: Logs / screenshots + description: Paste relevant logs or attach screenshots. + render: shell + - type: input + id: version + attributes: + label: Version / commit + placeholder: "v1.0.0 or commit hash" + - type: textarea + id: environment + attributes: + label: Environment + placeholder: "OS, Docker version, browser, etc." diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 0000000..f4d87dc --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,8 @@ +blank_issues_enabled: false +contact_links: + - name: 💬 Questions & discussion + url: https://github.com/cartesiosson/ai_act_project/discussions + about: Ask questions or discuss ideas about SERAMIS here. + - name: 🔒 Report a security vulnerability + url: https://github.com/cartesiosson/ai_act_project/security/advisories/new + about: Please report vulnerabilities privately, not as public issues. diff --git a/.github/ISSUE_TEMPLATE/feature_request.yml b/.github/ISSUE_TEMPLATE/feature_request.yml new file mode 100644 index 0000000..07beb74 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/feature_request.yml @@ -0,0 +1,43 @@ +name: ✨ Feature request +description: Suggest an idea or enhancement for SERAMIS +title: "[Feature]: " +labels: ["enhancement", "triage"] +body: + - type: textarea + id: problem + attributes: + label: Problem / motivation + description: Is your feature request related to a problem? Please describe. + placeholder: "I'm always frustrated when..." + validations: + required: true + - type: textarea + id: solution + attributes: + label: Proposed solution + description: A clear and concise description of what you want to happen. + validations: + required: true + - type: dropdown + id: area + attributes: + label: Area + options: + - Frontend (React UI) + - Backend (FastAPI) + - Reasoner service + - Forensic agent + - MCP SPARQL server + - Ontology / semantic resources + - Documentation + - Other + validations: + required: true + - type: textarea + id: alternatives + attributes: + label: Alternatives considered + - type: textarea + id: context + attributes: + label: Additional context diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..d65cd7c --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,30 @@ + + +## Description + + + +## Related issue + + + +## Type of change + +- [ ] 🐛 Bug fix +- [ ] ✨ New feature +- [ ] 📝 Documentation +- [ ] 🧠 Ontology / semantic resources +- [ ] ♻️ Refactor +- [ ] 🔒 Security + +## Checklist + +- [ ] My code follows the project's [coding guidelines](../CONTRIBUTING.md) +- [ ] I built/ran the affected services locally +- [ ] I updated documentation / `CHANGELOG` where relevant +- [ ] I did **not** commit secrets (`.env` stays git-ignored) +- [ ] Ontology changes (if any) preserve backwards compatibility or are noted + +## Screenshots / notes + + diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml new file mode 100644 index 0000000..000866d --- /dev/null +++ b/.github/workflows/ci.yml @@ -0,0 +1,49 @@ +name: CI + +on: + push: + branches: [main] + pull_request: + branches: [main] + +permissions: + contents: read + +concurrency: + group: ci-${{ github.ref }} + cancel-in-progress: true + +jobs: + frontend-build: + name: Frontend build + runs-on: ubuntu-latest + defaults: + run: + working-directory: frontend + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-node@v4 + with: + node-version: "20" + cache: npm + cache-dependency-path: frontend/package-lock.json + - name: Install dependencies + run: npm ci + - name: Build + run: npm run build + + python-checks: + name: Python syntax & lint + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: "3.11" + - name: Byte-compile all services (syntax check) + run: python -m compileall -q backend reasoner_service forensic_agent mcp-servers + - name: Lint with Ruff (advisory) + continue-on-error: true + run: | + python -m pip install --upgrade pip ruff + ruff check backend reasoner_service forensic_agent mcp-servers diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 0000000..62e952d --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,32 @@ +cff-version: 1.2.0 +message: "If you use SERAMIS in your research, please cite it as below." +title: "SERAMIS — Semantic Reasoning and AI Management Intelligent System" +abstract: >- + SERAMIS is an automated semantic assessment platform for compliance with the + European Union Artificial Intelligence Act (EU AI Act). It combines a formal + OWL ontology with SWRL/SHACL inference rules to automatically derive + compliance requirements, risk classifications and regulatory obligations, + with multi-framework mappings to ISO/IEC 42001, NIST AI RMF and W3C DPV. +type: software +version: 1.0.0 +date-released: 2026-06-16 +license: MIT +repository-code: "https://github.com/cartesiosson/ai_act_project" +url: "https://github.com/cartesiosson/ai_act_project" +keywords: + - EU AI Act + - ontology + - semantic reasoning + - SWRL + - SHACL + - regulatory compliance + - knowledge graph + - DPV + - ISO 42001 + - NIST AI RMF +authors: + - family-names: "Fernández González" + given-names: "David" + - family-names: "Ortega de Mues" + given-names: "Mariano" + affiliation: "Universidad Internacional de La Rioja (UNIR)" diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md new file mode 100644 index 0000000..5cfa905 --- /dev/null +++ b/CODE_OF_CONDUCT.md @@ -0,0 +1,57 @@ +# Contributor Covenant Code of Conduct + +## Our Pledge + +We as members, contributors, and leaders pledge to make participation in our +community a harassment-free experience for everyone, regardless of age, body +size, visible or invisible disability, ethnicity, sex characteristics, gender +identity and expression, level of experience, education, socio-economic status, +nationality, personal appearance, race, religion, or sexual identity and +orientation. + +We pledge to act and interact in ways that contribute to an open, welcoming, +diverse, inclusive, and healthy community. + +## Our Standards + +Examples of behavior that contributes to a positive environment include: + +- Demonstrating empathy and kindness toward other people +- Being respectful of differing opinions, viewpoints, and experiences +- Giving and gracefully accepting constructive feedback +- Accepting responsibility and apologizing to those affected by our mistakes +- Focusing on what is best for the overall community + +Examples of unacceptable behavior include: + +- The use of sexualized language or imagery, and sexual attention or advances +- Trolling, insulting or derogatory comments, and personal or political attacks +- Public or private harassment +- Publishing others' private information without explicit permission +- Other conduct which could reasonably be considered inappropriate in a + professional setting + +## Enforcement Responsibilities + +Community leaders are responsible for clarifying and enforcing our standards and +will take appropriate and fair corrective action in response to any behavior +that they deem inappropriate, threatening, offensive, or harmful. + +## Scope + +This Code of Conduct applies within all community spaces, and also applies when +an individual is officially representing the community in public spaces. + +## Enforcement + +Instances of abusive, harassing, or otherwise unacceptable behavior may be +reported to the project maintainers at **mariano.ortegademues@gmail.com**. +All complaints will be reviewed and investigated promptly and fairly. + +## Attribution + +This Code of Conduct is adapted from the [Contributor Covenant][homepage], +version 2.1, available at +https://www.contributor-covenant.org/version/2/1/code_of_conduct.html + +[homepage]: https://www.contributor-covenant.org diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..4c7adfb --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,92 @@ +# Contributing to SERAMIS + +First off, thank you for taking the time to contribute! 🎉 + +SERAMIS is an academic and open-source project. Contributions of all kinds are +welcome: bug reports, feature proposals, documentation improvements, ontology +refinements and code. + +## Table of Contents + +- [Code of Conduct](#code-of-conduct) +- [How can I contribute?](#how-can-i-contribute) +- [Development setup](#development-setup) +- [Branching and commits](#branching-and-commits) +- [Pull request process](#pull-request-process) +- [Coding guidelines](#coding-guidelines) +- [Reporting security issues](#reporting-security-issues) + +## Code of Conduct + +This project and everyone participating in it is governed by the +[Code of Conduct](CODE_OF_CONDUCT.md). By participating, you are expected to +uphold it. + +## How can I contribute? + +- **Reporting bugs** — open an issue using the *Bug report* template. Include + steps to reproduce, the affected service, and logs where possible. +- **Suggesting features** — open an issue using the *Feature request* template. +- **Improving the ontology** — changes under `ontologias/` should preserve + backwards compatibility where possible and update `ontologias/CHANGELOG.md`. +- **Code** — pick an open issue (or open one first to discuss) and submit a PR. + +## Development setup + +The full stack runs via Docker Compose: + +```bash +cp .env.example .env # adjust values; never commit your .env +docker compose up --build +``` + +Services and ports: + +| Service | Port | Description | +|------------------|-------|--------------------------------------| +| Frontend (Vite) | 5173 | React UI | +| Backend (FastAPI)| 8000 | Core derivation & requirements API | +| Reasoner | 8001 | SWRL/Pellet inference | +| Forensic agent | 8002 | LLM incident analysis (ReAct) | +| MCP SPARQL | 8080 | Model Context Protocol SPARQL server | +| Ontology docs | 80 | Static ontology documentation | +| Fuseki | 3030 | RDF triple store | +| MongoDB | 27017 | Document persistence | +| Ollama | 11434 | Local LLM provider | + +For frontend-only work: + +```bash +cd frontend +npm ci +npm run dev +``` + +## Branching and commits + +- Branch from `main` using a descriptive prefix: + `feat/...`, `fix/...`, `docs/...`, `chore/...`, `refactor/...`. +- Write clear, imperative commit messages (e.g. `fix: escape IRIs in SPARQL delete`). +- Keep commits focused; avoid mixing unrelated changes. + +## Pull request process + +1. Ensure the project builds (`npm run build` in `frontend/`; services start + under `docker compose`). +2. Update documentation and `CHANGELOG` entries where relevant. +3. Fill in the PR template and link the related issue. +4. At least one maintainer review is required before merge. + +## Coding guidelines + +- **Python**: follow PEP 8. Prefer explicit error handling over bare `except`. + Validate and sanitize any user input that reaches a SPARQL or database query. +- **TypeScript/React**: keep `strict` mode clean; avoid `any`; prefer small, + composable components. +- Do not commit secrets. Use `.env` (git-ignored) and keep `.env.example` + populated with safe placeholder values only. + +## Reporting security issues + +Please do **not** open public issues for security vulnerabilities. See +[SECURITY.md](SECURITY.md) for responsible disclosure instructions. diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..0b83bd0 --- /dev/null +++ b/LICENSE @@ -0,0 +1,36 @@ +MIT License + +Copyright (c) 2026 David Fernández González, Mariano Ortega de Mues +SERAMIS — Semantic Reasoning and AI Management Intelligent System +Universidad Internacional de La Rioja (UNIR) + +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. + +--- + +NOTE ON DUAL LICENSING: + +This MIT license applies to the SOURCE CODE of the SERAMIS project. + +The ontology and semantic resources (files under `ontologias/`, including OWL, +TTL, JSON-LD and SHACL artifacts) are licensed separately under +Creative Commons Attribution 4.0 International (CC BY 4.0). +See https://creativecommons.org/licenses/by/4.0/ + +Third-party dependency licenses are documented in LICENSES. diff --git a/LICENSES b/LICENSES index fef1fb9..14b18ac 100644 --- a/LICENSES +++ b/LICENSES @@ -8,9 +8,10 @@ This document lists the open source licenses for all third-party dependencies us **SERAMIS** (Semantic Reasoning and AI Management Intelligent System) ha sido desarrollado como Trabajo Fin de Máster en el programa de **Máster en Inteligencia Artificial** de la **Universidad Internacional de La Rioja (UNIR)**. -La ontología y los recursos semánticos están licenciados bajo **Creative Commons Attribution 4.0 International (CC BY 4.0)**. +SERAMIS se publica bajo un esquema de **licencia dual**: -El código fuente está disponible bajo los términos definidos por UNIR para Trabajos Fin de Máster, cumpliendo con la normativa de propiedad intelectual de la universidad. +- **El código fuente** está licenciado bajo la **MIT License** (ver el archivo `LICENSE`). +- **La ontología y los recursos semánticos** (directorio `ontologias/`) están licenciados bajo **Creative Commons Attribution 4.0 International (CC BY 4.0)**. --- diff --git a/README.md b/README.md index 160427c..09c33e6 100644 --- a/README.md +++ b/README.md @@ -16,7 +16,9 @@ Ontology DPV 2.2 ELI - License + Code License: MIT + Ontology License: CC BY 4.0 + CI

--- @@ -923,9 +925,14 @@ Estas cifras dependen del modelo LLM local (`llama3.2:3b`); un modelo mayor mejo ## 13. Licencia -Este proyecto utiliza la ontología EU AI Act licenciada bajo **Creative Commons Attribution 4.0 International (CC BY 4.0)**. +Este proyecto se publica bajo un esquema de **licencia dual**: -El código fuente está disponible bajo los términos definidos por UNIR para Trabajos Fin de Máster. +- **Código fuente** — [MIT License](LICENSE). +- **Ontología y recursos semánticos** (directorio `ontologias/`) — **Creative Commons Attribution 4.0 International (CC BY 4.0)**. + +Las licencias de las dependencias de terceros se documentan en [LICENSES](LICENSES). + +Si utilizas SERAMIS en tu investigación, por favor cítalo según [CITATION.cff](CITATION.cff). --- diff --git a/SECURITY.md b/SECURITY.md new file mode 100644 index 0000000..499f689 --- /dev/null +++ b/SECURITY.md @@ -0,0 +1,47 @@ +# Security Policy + +## Supported Versions + +| Version | Supported | +|---------|--------------------| +| 1.0.x | :white_check_mark: | +| < 1.0 | :x: | + +## Reporting a Vulnerability + +We take the security of SERAMIS seriously. If you discover a security +vulnerability, please report it **privately** so we can address it before +public disclosure. + +**Please do not open a public GitHub issue for security vulnerabilities.** + +Instead, use one of the following channels: + +- GitHub's [private vulnerability reporting](https://github.com/cartesiosson/ai_act_project/security/advisories/new) + (preferred), or +- Email **mariano.ortegademues@gmail.com** with the subject line + `[SECURITY] SERAMIS`. + +Please include: + +- A description of the vulnerability and its potential impact +- Steps to reproduce (proof of concept where possible) +- The affected service/component and version + +We aim to acknowledge reports within **5 business days** and to provide a +remediation timeline after triage. + +## Scope and known considerations + +SERAMIS is a research/academic platform. The default Docker Compose setup is +intended for **local or trusted-network deployment** and ships without +authentication and with development default credentials. Before exposing any +service to an untrusted network you should, at minimum: + +- Replace all default credentials in `.env` (never use `admin`). +- Restrict CORS to known origins. +- Place the services behind an authenticating reverse proxy / TLS. +- Validate and sanitize any externally supplied input that reaches SPARQL or + database queries. + +These hardening items are tracked in the project issues.