a4db3e62ec
Addresses the documentation-layer gap after Phase A/B moved the git REMOTE from
GitHub to Codeberg but left ~100 project-self GitHub URLs embedded in markdown,
HTML, JS, and Python files. The remote-layer migration was generalised as
"GitHub is gone from the codebase" without verifying the content layer.
22 files swept in this commit. 27 additional files hold pre-existing inst_016/017/018
or inst_084 debt that would transfer on touch (hook whole-file scan). Those
await a companion hygiene-first commit before their GitHub->Codeberg flip
can land cleanly.
Sweep scope this commit:
- README.md, SECURITY.md
- 3 For-Claude-Web bundle files (GitHub URLs noted as "separate concern" in
today's earlier licence-swap commits)
- docs/markdown/deployment-guide.md
- docs/AUTOMATED_SYNC_SETUP, PLURALISM_CHECKLIST, github/AGENT_LIGHTNING_README
- docs/business-intelligence/governance-bi-tools
- docs/outreach/EXECUTIVE-BRIEF-BI-GOVERNANCE (+ v2)
- docs/research/ARCHITECTURAL-SAFEGUARDS-*
- email-templates/README.md, base-template.html
- 3 scripts/seed-*-blog-post.js (blog-seeding scripts)
- scripts/upload-document.js
- SESSION_HANDOFF_2025-10-23_FRAMEWORK_ANALYSIS.md
- SECURITY_INCIDENT_POST_MORTEM_2025-10-21.md
Pattern swaps (longest-first):
github.com/AgenticGovernance/tractatus-framework/issues -> codeberg.org/mysovereignty/tractatus-framework/issues
github.com/AgenticGovernance/tractatus-framework/discussions -> .../issues (Codeberg has no discussions feature)
github.com/AgenticGovernance/tractatus-framework.git -> codeberg.org/mysovereignty/tractatus-framework.git
github.com/AgenticGovernance/tractatus-framework -> codeberg.org/mysovereignty/tractatus-framework
git@github.com:AgenticGovernance/... -> git@codeberg.org:mysovereignty/...
github.com/AgenticGovernance/tractatus (old org/repo path) -> codeberg.org/mysovereignty/tractatus-framework
AgenticGovernance/tractatus-framework (bare) -> mysovereignty/tractatus-framework
Hook validator update (scripts/hook-validators/validate-credentials.js):
PROTECTED_VALUES.github_org: 'AgenticGovernance' -> 'mysovereignty'
PROTECTED_VALUES.license: 'Apache License 2.0' -> EUPL-1.2 long form
URL detection regex: /github\.com\/.../ -> /codeberg\.org\/.../
Placeholder checks + error messages updated to reflect Codeberg as
authoritative post-migration host. Key names (e.g. `github_org`) retained
for backward compatibility with validate-file-edit.js.
Held back from this commit (27 files total, documented reasons):
11 historical session handoffs / closedown docs / incident reports
(2025-10 through 2026-02) — modifying them rewrites the record to contain
URLs that did not exist at the time of writing, AND ownership of their
pre-existing inst_084 exposures transfers on touch.
8 live-content docs with pre-existing inst_084 debt (port/API-endpoint/
file-path exposures): docs/markdown/case-studies.md, technical-architecture,
introduction-to-the-tractatus-framework, implementation-guide-v1.1,
docs/plans/integrated-implementation-roadmap-2025, docs/governance/*,
docs/ANTHROPIC_*, docs/GOVERNANCE_SERVICE_*, docs/RESEARCH_DOCUMENTATION_*,
deployment-quickstart/*.
8 live-content docs with pre-existing inst_016/017/018 debt:
CHANGELOG.md, CONTRIBUTING.md, docs/LAUNCH_ANNOUNCEMENT, LAUNCH_CHECKLIST,
PHASE_4_REPOSITORY_ANALYSIS, PHASE_6_SUMMARY, docs/plans/research-enhancement-
roadmap-2025, docs/case-studies/pre-publication-audit-oct-2025.
Also NOT in this commit (separate concerns):
- scripts/add-inst-084-github-url-protection.js (detection-rule logic needs
framework-level decision on post-migration semantics).
- .claude/* (framework state).
- docs/PRODUCTION_DOCUMENTS_EXPORT.json (DB dump).
- package-lock.json (npm sponsor URLs, third-party).
- .git/config embedded credentials (requires out-of-band rotation on both
remote hosts + auth-strategy decision; user-action task).
Context: today's EUPL-1.2 sweep closed the licence-text-content layer
(5c386d0d / 6d49bfbf / ab0a6af4 / 4c1a26e8). This commit starts closing the
matching vendor-URL-content layer. Next: hygiene-first pass on the 16
live-content docs held back, then a second URL-flip pass on them.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
176 lines
5.9 KiB
Markdown
176 lines
5.9 KiB
Markdown
# Security Policy
|
|
|
|
## Reporting Security Vulnerabilities
|
|
|
|
The Tractatus Framework takes security seriously. We appreciate your efforts to responsibly disclose your findings.
|
|
|
|
### Where to Report
|
|
|
|
**Please DO NOT report security vulnerabilities through public GitHub issues.**
|
|
|
|
Instead, please report security vulnerabilities by emailing:
|
|
|
|
**security@agenticgovernance.digital**
|
|
|
|
### What to Include
|
|
|
|
To help us better understand and resolve the issue, please include as much of the following information as possible:
|
|
|
|
- **Type of vulnerability** (e.g., SQL injection, cross-site scripting, authentication bypass)
|
|
- **Full paths of affected source files**
|
|
- **Location of the affected code** (tag/branch/commit or direct URL)
|
|
- **Step-by-step instructions to reproduce the issue**
|
|
- **Proof-of-concept or exploit code** (if applicable)
|
|
- **Impact of the vulnerability** (what an attacker could achieve)
|
|
- **Suggested mitigation** (if you have one)
|
|
|
|
### What to Expect
|
|
|
|
When you report a vulnerability, you can expect:
|
|
|
|
1. **Acknowledgment**: We will acknowledge receipt of your report within **48 hours**
|
|
2. **Assessment**: We will assess the vulnerability and determine its severity
|
|
3. **Updates**: We will keep you informed of our progress
|
|
4. **Resolution**: We will work to release a fix as quickly as possible
|
|
5. **Credit**: With your permission, we will credit you in the security advisory
|
|
|
|
### Disclosure Policy
|
|
|
|
- We request that you give us a reasonable amount of time to address the vulnerability before public disclosure
|
|
- We will keep you informed of our remediation timeline
|
|
- Once a fix is released, we will publish a security advisory crediting you (unless you prefer to remain anonymous)
|
|
|
|
### Supported Versions
|
|
|
|
We currently support the following versions with security updates:
|
|
|
|
| Version | Supported |
|
|
| ------- | ------------------ |
|
|
| 3.5.x | ✅ Yes |
|
|
| < 3.5 | ❌ Not supported |
|
|
|
|
Only the latest minor version receives security updates. We strongly recommend keeping your installation up to date.
|
|
|
|
## Security Best Practices for Implementers
|
|
|
|
If you're implementing the Tractatus Framework in your own project, we recommend:
|
|
|
|
### 1. Environment Security
|
|
|
|
- **Never commit `.env` files** to version control
|
|
- **Rotate secrets regularly** (JWT secrets, API keys, database credentials)
|
|
- **Use strong passwords** for MongoDB and admin accounts
|
|
- **Enable MongoDB authentication** in production
|
|
- **Use TLS/SSL** for all connections in production
|
|
|
|
### 2. Network Security
|
|
|
|
- **Use firewalls** to restrict access to MongoDB and application ports
|
|
- **Enable rate limiting** (already configured in the framework)
|
|
- **Use reverse proxy** (nginx/Apache) with HTTPS
|
|
- **Configure CORS** appropriately for your use case
|
|
- **Monitor failed authentication attempts**
|
|
|
|
### 3. Deployment Security
|
|
|
|
- **Run as non-root user** (framework defaults to this)
|
|
- **Use Docker secrets** for sensitive configuration
|
|
- **Keep dependencies updated** (`npm audit` regularly)
|
|
- **Enable security headers** (already configured)
|
|
- **Disable debug logs** in production
|
|
|
|
### 4. Database Security
|
|
|
|
- **Create read-only database users** for reporting
|
|
- **Enable MongoDB access control**
|
|
- **Backup encryption keys** securely
|
|
- **Regular security audits** of database access logs
|
|
- **Implement data retention policies**
|
|
|
|
### 5. API Security
|
|
|
|
- **Validate all input** (framework provides validation middleware)
|
|
- **Sanitize error responses** (already configured)
|
|
- **Use authentication** for all admin endpoints
|
|
- **Implement request signing** for critical operations
|
|
- **Monitor for unusual API patterns**
|
|
|
|
## Known Security Considerations
|
|
|
|
### MongoDB Connection
|
|
|
|
The framework uses MongoDB for persistence. Ensure your MongoDB instance:
|
|
|
|
- Has authentication enabled
|
|
- Is not exposed to the public internet
|
|
- Uses encrypted connections (TLS)
|
|
- Has appropriate network firewall rules
|
|
- Is regularly backed up
|
|
|
|
### Rate Limiting
|
|
|
|
The framework includes rate limiting middleware configured for:
|
|
|
|
- **Public endpoints**: 100 requests per 15 minutes per IP
|
|
- **Adjustable limits**: See `src/config/app.config.js`
|
|
|
|
Adjust these limits based on your expected traffic and security requirements.
|
|
|
|
### Session Management
|
|
|
|
The framework uses MongoDB to store session state. Ensure:
|
|
|
|
- Sessions have appropriate timeouts
|
|
- Session data is regularly cleaned up
|
|
- Sensitive data is not stored in sessions
|
|
|
|
### Input Validation
|
|
|
|
All API endpoints include input validation middleware. However:
|
|
|
|
- Additional validation may be needed for your specific use case
|
|
- Always validate data at multiple layers
|
|
- Never trust client-side validation alone
|
|
|
|
## Security Updates
|
|
|
|
We will publish security advisories for any vulnerabilities discovered in the framework:
|
|
|
|
- **GitHub Security Advisories**: https://codeberg.org/mysovereignty/tractatus-framework/security/advisories
|
|
- **Mailing List**: Subscribe at https://agenticgovernance.digital for security notifications
|
|
|
|
## Compliance
|
|
|
|
The Tractatus Framework is designed with security best practices in mind:
|
|
|
|
- **OWASP Top 10**: Protections against common vulnerabilities
|
|
- **Input Validation**: All endpoints validate input
|
|
- **Output Encoding**: Responses are sanitized
|
|
- **Security Headers**: Helmet middleware with custom CSP
|
|
- **Error Handling**: No stack traces in production
|
|
|
|
## Security Audit History
|
|
|
|
| Date | Type | Findings | Status |
|
|
|------------|----------------|----------|----------|
|
|
| 2025-10-21 | Internal Review| 0 Critical| Resolved |
|
|
|
|
We welcome third-party security audits. Please contact us if you're interested in conducting an audit.
|
|
|
|
## Contact
|
|
|
|
For security-related questions or concerns:
|
|
|
|
- **Email**: security@agenticgovernance.digital
|
|
- **Documentation**: https://agenticgovernance.digital
|
|
- **GitHub Issues**: For non-security bugs only
|
|
|
|
## Acknowledgments
|
|
|
|
We would like to thank the following individuals for responsibly disclosing security vulnerabilities:
|
|
|
|
*(None reported yet - this is the initial release)*
|
|
|
|
---
|
|
|
|
**Thank you for helping keep Tractatus Framework and our community safe!**
|