Skip to content

Commit 4596440

Browse files
SecAI-Hubclaude
SecAI-Hub
and
claude
committed
Add comprehensive docs, trust files, schemas, examples, and README restructure
Discoverability: GitHub description, 14 topics, homepage link. Trust files: SECURITY.md, CONTRIBUTING.md, CODE_OF_CONDUCT.md, SUPPORT.md, CITATION.cff. LLM-friendly: llms.txt and llms-full.txt for AI agent discoverability. Docs: architecture, 5 component docs, 3 install guides, API reference, policy schema, FAQ, glossary, non-goals, service diagram, security status, test matrix, compatibility matrix, security test matrix. Schemas: OpenAPI 3.0 spec, JSON Schema for policy.yaml and appliance.yaml. Examples: 8 task-oriented walkthroughs plus annotated sample-policy.yaml. README: restructured with badges, "Who This Is For", docs index, collapsible roadmap, and links to detailed docs instead of inline walls of text. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
1 parent 629f655 commit 4596440

39 files changed

Lines changed: 7766 additions & 807 deletions

‎CITATION.cff‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
cff-version: 1.2.0
2+
title: SecAI OS
3+
message: "If you use this software, please cite it as below."
4+
type: software
5+
authors:
6+
- name: "SecAI-Hub Contributors"
7+
repository-code: "https://github.com/SecAI-Hub/SecAI_OS"
8+
license: Apache-2.0
9+
keywords:
10+
- secure-ai
11+
- local-llm
12+
- privacy
13+
- model-scanning
14+
- defense-in-depth
15+
- air-gapped-ai
16+
- supply-chain-security
17+
date-released: "2026-03-08"
18+
abstract: "Bootable local-first AI OS with sealed runtime, model quarantine pipeline, airlock egress controls, encrypted vault, and private Tor-routed search. Built on uBlue (Fedora Atomic)."

‎CODE_OF_CONDUCT.md‎

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
# Code of Conduct
2+
3+
This project adopts the [Contributor Covenant v2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
4+
5+
Please read the full text at the link above. All participants in this project are expected to uphold this code.
6+
7+
## Reporting
8+
9+
If you experience or witness unacceptable behavior, please report it by emailing **conduct@secai-hub.github.io**.
10+
11+
All reports will be reviewed and investigated promptly and fairly. The project team is obligated to maintain confidentiality with regard to the reporter of an incident.
12+
13+
## Enforcement
14+
15+
Project maintainers who do not follow or enforce this Code of Conduct may face temporary or permanent repercussions as determined by other members of the project's leadership.
16+
17+
## Attribution
18+
19+
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.

‎CONTRIBUTING.md‎

Lines changed: 189 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,189 @@
1+
# Contributing to SecAI OS
2+
3+
Thank you for your interest in contributing to SecAI OS. This document explains
4+
how to set up your development environment, run tests, and submit changes.
5+
6+
## Prerequisites
7+
8+
| Tool | Minimum Version | Purpose |
9+
|---|---|---|
10+
| Go | 1.22+ | Build Go services (registry, tool-firewall, airlock) |
11+
| Python | 3.11+ | Build Python services (quarantine, UI, search mediator) |
12+
| shellcheck | Latest | Lint shell scripts |
13+
| git | 2.x | Version control |
14+
15+
Optional but recommended:
16+
17+
- `gofmt` (included with Go) for formatting Go code.
18+
- `pip` or a virtual-environment manager (`venv`, `uv`) for Python dependencies.
19+
- `cosign` for verifying container image signatures.
20+
21+
## Local Development Setup
22+
23+
### 1. Clone the Repository
24+
25+
```bash
26+
git clone https://github.com/SecAI-Hub/SecAI_OS.git
27+
cd SecAI_OS
28+
```
29+
30+
### 2. Build Go Services
31+
32+
```bash
33+
cd services/registry && go build ./... && cd ../..
34+
cd services/tool-firewall && go build ./... && cd ../..
35+
cd services/airlock && go build ./... && cd ../..
36+
```
37+
38+
### 3. Install Python Dependencies
39+
40+
```bash
41+
python3 -m venv .venv
42+
source .venv/bin/activate
43+
pip install -r services/quarantine/requirements.txt
44+
pip install -r services/ui/requirements.txt
45+
pip install -r services/search-mediator/requirements.txt
46+
pip install pytest
47+
```
48+
49+
### 4. Verify Shell Scripts
50+
51+
```bash
52+
shellcheck files/system/usr/libexec/secure-ai/*.sh
53+
```
54+
55+
## Running Tests
56+
57+
### Go Tests (26 tests)
58+
59+
```bash
60+
cd services/registry && go test ./... -v && cd ../..
61+
cd services/tool-firewall && go test ./... -v && cd ../..
62+
cd services/airlock && go test ./... -v && cd ../..
63+
```
64+
65+
### Python Tests (595+ tests)
66+
67+
```bash
68+
pytest tests/ -v
69+
```
70+
71+
### Shell Linting
72+
73+
```bash
74+
shellcheck files/system/usr/libexec/secure-ai/*.sh
75+
```
76+
77+
### Run Everything
78+
79+
```bash
80+
# Go
81+
for svc in registry tool-firewall airlock; do
82+
(cd "services/$svc" && go test ./... -v)
83+
done
84+
85+
# Python
86+
pytest tests/ -v
87+
88+
# Shell
89+
shellcheck files/system/usr/libexec/secure-ai/*.sh
90+
```
91+
92+
## Coding Standards
93+
94+
### Go
95+
96+
- Format all Go code with `gofmt`. CI will reject unformatted code.
97+
- Follow standard Go conventions (effective Go, Go Code Review Comments).
98+
- Export only what is necessary; keep package APIs minimal.
99+
100+
### Python
101+
102+
- Follow [PEP 8](https://peps.python.org/pep-0008/).
103+
- Use type hints where practical.
104+
- Keep functions focused and testable.
105+
106+
### Shell
107+
108+
- Target POSIX sh unless bash-specific features are required.
109+
- All scripts must pass `shellcheck` with zero warnings.
110+
- Use `set -euo pipefail` at the top of bash scripts.
111+
112+
### General
113+
114+
- Keep commits atomic -- one logical change per commit.
115+
- Write clear, descriptive variable and function names.
116+
- Add or update tests for any new functionality.
117+
118+
## Pull Request Process
119+
120+
1. **Branch from `main`.** Create a feature branch with a descriptive name:
121+
```
122+
git checkout -b feat/short-description
123+
```
124+
125+
2. **Make your changes.** Follow the coding standards above.
126+
127+
3. **Run all tests locally.** Ensure Go tests, Python tests, and shellcheck
128+
all pass before pushing.
129+
130+
4. **Sign your commits.** Use `git commit -s` to add a Signed-off-by line,
131+
or configure GPG/SSH signing.
132+
133+
5. **Push and open a PR.** Target the `main` branch.
134+
135+
6. **Describe your changes.** In the PR description, explain:
136+
- What the change does and why it is needed.
137+
- How it was tested.
138+
- Any relevant issue numbers (use `Closes #N` or `Fixes #N`).
139+
140+
7. **Wait for CI.** All checks must pass before a PR will be reviewed.
141+
142+
8. **Respond to review feedback.** Push additional commits to address review
143+
comments rather than force-pushing.
144+
145+
## Commit Message Format
146+
147+
Use the following format for commit messages:
148+
149+
```
150+
<type>: <short summary>
151+
152+
<optional longer description>
153+
154+
Signed-off-by: Your Name <your.email@example.com>
155+
```
156+
157+
Where `<type>` is one of:
158+
159+
| Type | Meaning |
160+
|---|---|
161+
| `feat` | New feature |
162+
| `fix` | Bug fix |
163+
| `docs` | Documentation only |
164+
| `test` | Adding or updating tests |
165+
| `refactor` | Code change that neither fixes a bug nor adds a feature |
166+
| `chore` | Build, CI, or tooling changes |
167+
| `security` | Security-related change |
168+
169+
Example:
170+
171+
```
172+
feat: add tensor-level scanning to quarantine pipeline
173+
174+
Scan individual tensors in GGUF files for anomalous shapes and
175+
unexpected data types before promoting models to the trusted store.
176+
177+
Signed-off-by: Jane Doe <jane@example.com>
178+
```
179+
180+
## Reporting Issues
181+
182+
- **Bugs:** Open a [GitHub Issue](https://github.com/SecAI-Hub/SecAI_OS/issues).
183+
- **Security vulnerabilities:** See [SECURITY.md](SECURITY.md).
184+
- **Questions:** Use [GitHub Discussions](https://github.com/SecAI-Hub/SecAI_OS/discussions).
185+
186+
## License
187+
188+
By contributing to SecAI OS, you agree that your contributions will be licensed
189+
under the [Apache License 2.0](LICENSE).

0 commit comments

Comments
 (0)