Skip to content

Commit 58d7822

Browse files
petervartanianpetervartanian
committed
1
1 parent 79ccf2a commit 58d7822

File tree

20,097 files changed

+3059823
-0
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

20,097 files changed

+3059823
-0
lines changed

‎CONTRIBUTING.md‎

Lines changed: 147 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,147 @@
1+
# Contributing to omphalOS
2+
3+
Thank you for your interest in contributing to omphalOS. This document outlines how to contribute code, investigations, documentation, and bug reports.
4+
5+
## Code of Conduct
6+
7+
Be professional, respectful, and constructive. This is a tool for serious analytical work—maintain that standard in all interactions.
8+
9+
## How to Contribute
10+
11+
### 1. Bug Reports
12+
13+
Use GitHub Issues to report bugs. Include:
14+
- What you did (exact commands, case definitions)
15+
- What you expected
16+
- What actually happened
17+
- System information (OS, Python version, omphalOS commit SHA)
18+
19+
### 2. Investigation Contributions
20+
21+
Have a novel pattern for detecting evasion/proliferation? Contribute it:
22+
23+
**Steps**:
24+
1. Write SQL investigation following catalog conventions (Canon/Margin headers, CTE structure, LIMIT clause)
25+
2. Place in `core/sql/investigations/custom/custom_<initials>_<date>_<description>.sql`
26+
3. Create test case with synthetic data showing the pattern
27+
4. Document false positive scenarios
28+
5. Submit pull request with investigation + test + docs
29+
30+
**Example**:
31+
```sql
32+
-- Investigation: custom_jd_20260123_circular_flows
33+
-- Domain: all
34+
-- Intent: Detect circular shipment patterns (A→B→A)
35+
-- [Canon 01-60 + Margin 001-045]
36+
WITH ...
37+
```
38+
39+
### 3. Documentation Improvements
40+
41+
Found unclear docs? Submit PR with improvements. Follow existing tone (technical but accessible).
42+
43+
### 4. Code Contributions
44+
45+
**Before coding**:
46+
- Open an issue describing what you want to build
47+
- Discuss approach with maintainers
48+
- Get approval before significant work
49+
50+
**Code standards**:
51+
- Python: Follow PEP 8, use `black` formatter
52+
- Rust: Use `rustfmt`
53+
- Go: Use `gofmt`
54+
- All code must include docstrings/comments
55+
- No external dependencies without approval (offline-first requirement)
56+
57+
**Testing**:
58+
- All new investigations must have test cases
59+
- All code changes must not break existing tests
60+
- Run `pytest` before submitting
61+
62+
### 5. Security Contributions
63+
64+
Found a vulnerability? See SECURITY.md for responsible disclosure process.
65+
66+
**Do NOT** open public issues for security vulnerabilities.
67+
68+
## Contribution Requirements
69+
70+
### What You Can Submit
71+
72+
✅ **Allowed**:
73+
- SQL investigations using synthetic data
74+
- Documentation improvements
75+
- Bug fixes
76+
- Performance optimizations
77+
- New verifiers (additional languages)
78+
- UI enhancements
79+
- Test cases
80+
81+
❌ **Prohibited**:
82+
- Real trade data, PII, BCI, or classified information
83+
- Credentials, API keys, or secrets (even fake ones that look real)
84+
- Copyrighted material without attribution
85+
- Malicious code or backdoors
86+
87+
### Data Requirements
88+
89+
**CRITICAL**: All contributed data must be **synthetic and non-identifiable**.
90+
91+
- Do NOT include real company names, addresses, or transaction records
92+
- Do NOT include data derived from classified sources
93+
- Do NOT include proprietary data from commercial providers
94+
95+
When in doubt, generate synthetic test data using omphalOS's world builder.
96+
97+
## Pull Request Process
98+
99+
1. **Fork** the repository
100+
2. **Create branch**: `git checkout -b feature/your-feature-name`
101+
3. **Make changes**: Follow code standards above
102+
4. **Test**: Ensure `pytest` passes, run verification on sample cases
103+
5. **Commit**: Use clear commit messages explaining *why*, not just *what*
104+
6. **Push**: `git push origin feature/your-feature-name`
105+
7. **Open PR**: Describe changes, link to related issues, explain testing performed
106+
107+
**PR Requirements**:
108+
- Passes all CI checks (linting, tests, pack verification)
109+
- Includes documentation updates if changing user-facing behavior
110+
- Includes test cases for new functionality
111+
- No merge conflicts with `main`
112+
113+
## Review Process
114+
115+
Maintainers will review within 7 days. Expect:
116+
- Questions about design choices
117+
- Requests for additional tests or documentation
118+
- Style/formatting feedback
119+
120+
**Be patient**. This is a system used for national security work—thoroughness matters more than speed.
121+
122+
## License
123+
124+
By contributing, you agree that your contributions will be licensed under CC0 (public domain). You affirm that:
125+
- You have the right to submit the contribution
126+
- The contribution is your original work or properly attributed
127+
- The contribution contains no classified, proprietary, or sensitive information
128+
129+
## Recognition
130+
131+
Contributors will be acknowledged in:
132+
- `CONTRIBUTORS.md` file (if substantial contribution)
133+
- Release notes for version where contribution appears
134+
- Academic publications citing omphalOS (if contribution is methodologically significant)
135+
136+
## Questions?
137+
138+
Open a GitHub Discussion (not an Issue) for:
139+
- How to implement a feature
140+
- Design questions
141+
- General usage questions
142+
143+
Use Issues only for bugs and concrete feature requests.
144+
145+
---
146+
147+
**Thank you for helping make intelligence analysis more transparent, reproducible, and defensible.**

‎LICENSE‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
CC0 1.0 Universal
2+
3+
Statement of Purpose
4+
5+
The laws of most jurisdictions throughout the world automatically confer
6+
exclusive Copyright and Related Rights (defined below) upon the creator and
7+
subsequent owner(s) (each and all, an "owner") of an original work of
8+
authorship and/or a database (each, a "Work").
9+
10+
Certain owners wish to permanently relinquish those rights to a Work for the
11+
purpose of contributing to a commons of creative, cultural and scientific
12+
works ("Commons") that the public can reliably and without fear of later
13+
claims of infringement build upon, modify, incorporate in other works, reuse
14+
and redistribute as freely as possible in any form whatsoever and for any
15+
purposes, including without limitation commercial purposes. These owners may
16+
contribute to the Commons to promote the ideal of a free culture and the
17+
further production of creative, cultural and scientific works, or to gain
18+
reputation or greater distribution for their Work in part through the use and
19+
efforts of others.
20+
21+
For these and/or other purposes and motivations, and without any expectation
22+
of additional consideration or compensation, the person associating CC0 with a
23+
Work (the "Affirmer"), to the extent that he or she is an owner of Copyright
24+
and Related Rights in the Work, voluntarily elects to apply CC0 to the Work
25+
and publicly distribute the Work under its terms, with knowledge of his or her
26+
Copyright and Related Rights in the Work and the meaning and intended legal
27+
effect of CC0 on those rights.
28+
29+
This work was produced by the United States Government and is not subject to
30+
copyright protection in the United States. Foreign copyrights may apply.

‎README.md‎

Lines changed: 139 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
# omphalOS
2+
3+
**A polycentric, offline-first casework suite for export control and sanctions intelligence analysis.**
4+
5+
[![License: CC0](https://img.shields.io/badge/License-CC0-lightgrey.svg)](https://creativecommons.org/publicdomain/zero/1.0/)
6+
[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
7+
[![DOI](https://zenodo.org/badge/DOI/10.5281/zenodo.18344930.svg)](https://doi.org/10.5281/zenodo.18344930)
8+
9+
## Overview
10+
11+
omphalOS is computational infrastructure for intelligence analysis that prioritizes epistemic humility, transparency, and reproducibility over predictive optimization. The system surfaces patterns in trade data that merit analytical review while systematically documenting uncertainty, making it suitable for adversarial legal contexts where analytical reasoning must withstand scrutiny.
12+
13+
The architecture provides (i) polycentric verification through multiple independent implementations, (ii) offline-first operation in air-gapped environments, (iii) embedded procedural safeguards against overconfident assessments, (iv) human-readable SQL investigations under version control, and (v) checksummed artifacts enabling bit-identical re-execution.
14+
15+
Application domains include export control casework under EAR and ITAR, sanctions enforcement through OFAC and multilateral regimes, trade-based money laundering detection, supply chain risk analysis, and proliferation finance investigations.
16+
17+
The system explicitly rejects classification paradigms. It does not predict entity behavior, assign risk scores, or operate as real-time monitoring infrastructure. All analytical operations are batch-oriented and hypothesis-generating.
18+
19+
## Quick Start
20+
21+
```bash
22+
# Clone and verify
23+
git clone https://github.com/your-org/omphalOS
24+
cd omphalOS
25+
PYTHONPATH=core/src python -m omphalos.cli pack verify packs/INDEX.json
26+
27+
# Build world and execute case
28+
PYTHONPATH=core/src python -m omphalos.cli world build --profile hydrate --out hydrate/world
29+
PYTHONPATH=core/src python -m omphalos.cli case run hydrate/cases/case_chemicals.json --out hydrate/runs
30+
31+
# Verify and export
32+
PYTHONPATH=core/src python -m omphalos.cli case verify hydrate/runs/case_chemicals/<run_id>/
33+
PYTHONPATH=core/src python -m omphalos.cli export hydrate/runs/case_chemicals/<run_id>/packet.json
34+
```
35+
36+
See [TUTORIAL.md](docs/TUTORIAL.md) for detailed walkthrough.
37+
38+
## Architecture
39+
40+
The system operates through three core object types: (i) cases articulate investigative questions with defined scope and investigation selection, (ii) runs materialize cases against world-states producing checksummed artifacts, and (iii) packets structure analytical findings with explicit claims (observations and unknowns), annexes, and provenance chains.
41+
42+
Trust is distributed across independent implementations in Python (reference runtime), Rust (cryptographic attestation), and Go (independent SQL execution). A run achieves validity only when all verifiers agree on artifact integrity.
43+
44+
```
45+
┌───────────────────────────────────────────┐
46+
│ omphalOS │
47+
├───────────────────────────────────────────┤
48+
│ Cases → Python Runtime → SQL Warehouse │
49+
│ ↓ │
50+
│ Run Artifacts (Packets) │
51+
│ ↓ │
52+
│ ┌────────┬────────┬────────┐ │
53+
│ │ Rust │ Go │ Export │ │
54+
│ │ Verify │ Verify │ Gate │ │
55+
│ └────────┴────────┴────────┘ │
56+
└───────────────────────────────────────────┘
57+
```
58+
59+
See [ARCHITECTURE.md](docs/ARCHITECTURE.md) for complete system design.
60+
61+
## Documentation
62+
63+
| Document | Coverage |
64+
|----------|----------|
65+
| [TUTORIAL.md](docs/TUTORIAL.md) | First case walkthrough |
66+
| [ARCHITECTURE.md](docs/ARCHITECTURE.md) | System design and verification |
67+
| [CANON.md](docs/CANON.md) | Epistemic humility as architectural principle |
68+
| [INVESTIGATIONS.md](docs/INVESTIGATIONS.md) | SQL catalog and pattern taxonomy |
69+
| [THREAT_MODEL.md](docs/THREAT_MODEL.md) | Security assumptions and mitigations |
70+
| [DEPLOYMENT.md](docs/DEPLOYMENT.md) | Production deployment and scaling |
71+
| [RESEARCH.md](docs/RESEARCH.md) | Academic positioning and research agenda |
72+
73+
## Design Philosophy
74+
75+
Traditional algorithmic systems for intelligence analysis optimize for precision and recall, treating detection as a classification problem. This approach fails in domains where (i) base rates are exceptionally low (illicit transactions represent less than 0.01% of flows), (ii) adversaries adapt to disclosed detection logic through FOIA and litigation, and (iii) analytical conclusions must withstand adversarial legal scrutiny requiring transparent reasoning.
76+
77+
omphalOS inverts this paradigm. Rather than classification, the system provides hypothesis-generating pattern detection that surfaces anomalies without labeling them. Rather than concealing analytical methods, it assumes disclosure and designs for transparency. Rather than confident predictions, it systematically documents unknowns alongside observations.
78+
79+
The Canon—sixty repetitions of "interpret with restraint; prefer simpler explanations; record unknowns" embedded in every SQL investigation—makes epistemic humility structurally unavoidable. This design draws from research demonstrating that single warnings are psychologically distant while repeated environmental cues durably shift judgment patterns.
80+
81+
See [CANON.md](docs/CANON.md) for philosophical foundation.
82+
83+
## Investigation Catalog
84+
85+
The catalog contains 20,000 parametric SQL queries detecting patterns including (i) payment fragmentation indicating threshold evasion, (ii) entity clustering revealing shell company networks, (iii) temporal anomalies preceding sanctions implementation, (iv) cross-domain procurement suggesting proliferation activity, and (v) price outliers indicating transfer pricing or barter.
86+
87+
Each investigation includes Canon and Margin headers providing epistemic safeguards, metadata documenting domain scope and analytical intent, CTE-based SQL for reviewability, and limited result sets preventing analyst overwhelm.
88+
89+
See [INVESTIGATIONS.md](docs/INVESTIGATIONS.md) for complete pattern taxonomy.
90+
91+
## Polycentric Verification
92+
93+
| Implementation | Language | Function |
94+
|----------------|----------|----------|
95+
| Python | 3.10+ | Reference runtime and case orchestration |
96+
| Rust | 1.70+ | Cryptographic attestation and schema validation |
97+
| Go | 1.20+ | Independent SQL execution and result verification |
98+
99+
This architecture defends against implementation bugs, supply chain compromises, and single points of failure. Trust is distributed rather than concentrated.
100+
101+
## Security and Privacy
102+
103+
**Export Control Notice**: This software is publicly released and not subject to export controls under the Export Administration Regulations. It contains no controlled technical data. Included datasets are synthetic and non-identifiable.
104+
105+
**Privacy by Design**: Packets contain aggregates rather than individual transaction details. Export gates block credentials and secrets before artifacts leave secure environments. World-states for demonstration are synthetic; production deployments apply redaction protocols.
106+
107+
See [THREAT_MODEL.md](docs/THREAT_MODEL.md) and [SECURITY.md](SECURITY.md) for threat analysis and disclosure policy.
108+
109+
## Contributing
110+
111+
Contributions are welcome following guidelines in [CONTRIBUTING.md](CONTRIBUTING.md) and security protocols in [SECURITY.md](SECURITY.md).
112+
113+
Requirements: (i) all data must be synthetic and non-identifiable, (ii) SQL investigations must follow Canon and Margin conventions, (iii) code must pass verification, (iv) no credentials or classified material.
114+
115+
## License
116+
117+
CC0 1.0 Universal (Public Domain)
118+
119+
This work was produced by the United States Government and is not subject to copyright protection in the United States. Foreign copyrights may apply. To the extent possible under law, all copyright and related rights have been dedicated to the public domain worldwide.
120+
121+
See [LICENSE](LICENSE) for complete text.
122+
123+
## Citation
124+
125+
```bibtex
126+
@software{omphalos2026,
127+
author = {{U.S. Government}},
128+
title = {omphalOS: A Polycentric Architecture for Epistemically Humble Intelligence Analysis},
129+
year = {2026},
130+
doi = {10.5281/zenodo.18344930},
131+
url = {https://github.com/your-org/omphalOS}
132+
}
133+
```
134+
135+
## Acknowledgments
136+
137+
Development influenced by Richards Heuer's *Psychology of Intelligence Analysis* (structured analytic techniques), Elinor Ostrom's polycentric governance theory, the CompCert verified software project, and the open-source intelligence community.
138+
139+
The system is designed to be transparent not because it has nothing to hide, but because transparency is what makes it defensible.

‎RUNBOOK.txt‎

Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
RUNBOOK
2+
3+
Verify packs:
4+
PYTHONPATH=core/src python -m omphalos.cli pack verify packs/INDEX.json
5+
6+
Inspect hydrated content:
7+
hydrate/world/meta.json
8+
hydrate/cases/case_chemicals.json
9+
hydrate/runs/case_chemicals/<run_id>/
10+
11+
Run again:
12+
PYTHONPATH=core/src python -m omphalos.cli case run hydrate/cases/case_chemicals.json --out hydrate/runs
13+
14+
Verify a run:
15+
PYTHONPATH=core/src python -m omphalos.cli case verify hydrate/runs/case_chemicals/<run_id>/
16+
17+
Export gate:
18+
PYTHONPATH=core/src python -m omphalos.cli export hydrate/runs/case_chemicals/<run_id>/packet.json

0 commit comments

Comments
 (0)