Skip to content

📚 Automated Documentation Update #16

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
github-actions wants to merge 7 commits into
base: master
Choose a base branch
from
Open

📚 Automated Documentation Update #16

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
7 commits
Select commit Hold shift + click to select a range
bee842e
docs: Initialize documentation pipeline [skip ci]
github-actions[bot] Jun 4, 2026
ebabe1c
chore(docs): Clean slate - remove all documentation (101 files) [skip…
github-actions[bot] Jun 4, 2026
b60a567
docs: Stage 1 - Inline documentation (235 files) [skip ci]
github-actions[bot] Jun 4, 2026
1a51515
chore(docs): Remove 1 orphaned inline files [skip ci]
github-actions[bot] Jun 4, 2026
c7b63ef
docs: Stage 2 - Architecture analysis (16 files) [skip ci]
github-actions[bot] Jun 4, 2026
47821fd
docs: Stage 3 - Tutorial generation (11 files) [skip ci]
github-actions[bot] Jun 4, 2026
5664a95
docs: Stage 4 - Repository documentation (4 files) [skip ci]
github-actions[bot] Jun 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
The table of contents is too big for display.
Diff view
Diff view
  •  
  •  
  •  
437 changes: 210 additions & 227 deletions CONTRIBUTING.md
View file
Open in desktop

Large diffs are not rendered by default.

289 changes: 131 additions & 158 deletions README.md
View file
Open in desktop

Large diffs are not rendered by default.

148 changes: 84 additions & 64 deletions docs/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# osquery — OpenFrame Edition Documentation
# osquery — OpenFrame Edition: Documentation

Welcome to the documentation for **osquery with OpenFrame** — the cross-platform OS instrumentation framework extended with AI-driven MSP automation by [Flamingo](https://flamingo.run) and [OpenFrame](https://openframe.ai).
Welcome to the documentation for **osquery with the OpenFrame integration** — the SQL-powered OS instrumentation framework for the [Flamingo](https://flamingo.run) MSP platform.

---

Expand All @@ -11,108 +11,128 @@ Welcome to the documentation for **osquery with OpenFrame** — the cross-platfo
- [Reference Architecture](#-reference-architecture)
- [Architecture Diagrams](#-architecture-diagrams)
- [Quick Links](#-quick-links)
- [Community](#-community)

---

## 🚀 Getting Started

New to osquery? Start here.
New to osquery? Start here for a guided introduction, prerequisites, and your first running query.

| Guide | Description |
|---|---|
| [Introduction](./getting-started/introduction.md) | What is osquery with OpenFrame? Features and target audience |
| [Prerequisites](./getting-started/prerequisites.md) | System requirements, supported platforms, required software |
| [Quick Start](./getting-started/quick-start.md) | Clone, build, and run osquery in under 10 minutes |
| [First Steps](./getting-started/first-steps.md) | Explore virtual tables, scheduled packs, FIM, extensions, and OpenFrame |
|-------|-------------|
| [Introduction](./getting-started/introduction.md) | What osquery is, key features, and the OpenFrame integration overview |
| [Prerequisites](./getting-started/prerequisites.md) | Hardware requirements, supported OS, required tools, and environment setup |
| [Quick Start](./getting-started/quick-start.md) | Build and run osquery in under 5 minutes |
| [First Steps](./getting-started/first-steps.md) | Explore key features, scheduled queries, events, and SQL patterns after your first build |

**Recommended reading order:** Introduction → Prerequisites → Quick Start → First Steps
---

## 🛠️ Development

Guides for contributors and platform engineers working on the codebase.

| Guide | Description |
|-------|-------------|
| [Development Overview](./development/README.md) | Technology stack, project layout, quick developer commands, and community links |
| [Environment Setup](./development/setup/environment.md) | IDE recommendations (VS Code, CLion, Xcode, Visual Studio), toolchain setup, ccache, and sanitizers |
| [Local Development](./development/setup/local-development.md) | Clone, configure, build targets, run, watch-mode iteration, and debug configuration |
| [Architecture Overview](./development/architecture/README.md) | System architecture diagrams, boot flow, SQL execution data flow, and key design decisions |
| [Security Guidelines](./development/security/README.md) | Auth patterns, token storage, TLS configuration, input validation, and least-privilege setup |
| [Testing Guide](./development/testing/README.md) | Test structure, running tests, writing unit and integration tests, benchmarks, and CI matrix |
| [Contributing Guidelines](./development/contributing/guidelines.md) | Code style, branching, commit messages, pull request process, and review checklist |

---

## 🛠 Development
## 📖 Reference Architecture

Guides for contributors and developers building on or extending osquery.
Deep-dive technical reference documentation for every major module, generated from source code analysis.

### Setup
### Core Runtime

| Guide | Description |
|---|---|
| [Environment Setup](./development/setup/environment.md) | IDE recommendations, clangd, ccache, editor extensions |
| [Local Development](./development/setup/local-development.md) | Build configurations, debug flags, GDB/LLDB, VS Code debugging |
| Module | Description |
|--------|-------------|
| [Core Init And Runtime](./reference/architecture/core-init-and-runtime/core-init-and-runtime.md) | Lifecycle orchestration — flag parsing, plugin activation, watcher/worker model, graceful shutdown |
| [Config And Packs](./reference/architecture/config-and-packs/config-and-packs.md) | Configuration loading, query scheduling, pack management, and config refresh lifecycle |
| [Config Plugins](./reference/architecture/config-plugins/config-plugins.md) | Configuration retrieval and parsing plugin implementations |

### Architecture
### SQL and Query Engine

| Guide | Description |
|---|---|
| [Architecture Overview](./development/architecture/README.md) | High-level module breakdown, runtime lifecycle, design decisions |
| Module | Description |
|--------|-------------|
| [SQL Core And Virtual Tables](./reference/architecture/sql-core-and-virtual-tables/sql-core-and-virtual-tables.md) | Embedded SQLite engine, virtual table integration, constraint pushdown, result diffing |
| [Query Execution And Logging](./reference/architecture/query-execution-and-logging/query-execution-and-logging.md) | Differential logging model, query state persistence, epoch and counter management |

### Quality
### Storage and Events

| Guide | Description |
|---|---|
| [Testing Guide](./development/testing/README.md) | GTest/GMock structure, running tests, writing unit and integration tests |
| [Security Best Practices](./development/security/README.md) | Auth patterns, AES-256-GCM, SQL authorizer, TLS, secrets management |
| Module | Description |
|--------|-------------|
| [Database Backends](./reference/architecture/database-backends/database-backends.md) | RocksDB persistent storage, ephemeral in-memory backend, domain keyspaces, migrations |
| [Events Core](./reference/architecture/events-core/events-core.md) | Publish/subscribe event framework, event publishers, subscriber plugins, backing store |

### Contributing
### Distributed and Networking

| Guide | Description |
|---|---|
| [Contributing Guidelines](./development/contributing/guidelines.md) | Code style, branch naming, commit format, PR process, virtual table creation |
| Module | Description |
|--------|-------------|
| [Distributed Querying](./reference/architecture/distributed-querying/distributed-querying.md) | Remote query orchestration, TLS distributed plugin, denylisting, concurrency control |
| [Remote HTTP Client](./reference/architecture/remote-http-client/remote-http-client.md) | Boost.Asio + OpenSSL HTTP/HTTPS transport, timeout handling, proxy support |

---
### Extensions and Plugins

## 📖 Reference Architecture
| Module | Description |
|--------|-------------|
| [Extensions Framework](./reference/architecture/extensions-framework/extensions-framework.md) | Apache Thrift IPC, runtime plugin injection, extension manager, SDK |
| [Plugin Interfaces And Logging](./reference/architecture/plugin-interfaces-and-logging/plugin-interfaces-and-logging.md) | LoggerPlugin interface, status log routing, snapshot and diff result forwarding |

Deep technical documentation for each core subsystem — generated directly from source code analysis.
### Utilities

| Module | Description |
|---|---|
| [Core Init And Runtime](./reference/architecture/core-init-and-runtime/core-init-and-runtime.md) | Process bootstrap, flags, watcher/worker model, watchdog |
| [SQL Engine And Virtual Tables](./reference/architecture/sql-engine-and-virtual-tables/sql-engine-and-virtual-tables.md) | SQLite engine, authorizer, virtual table binding, constraint pushdown |
| [Configuration And Packs](./reference/architecture/configuration-and-packs/configuration-and-packs.md) | Config loading, packs, schedulers, decorators, change detection |
| [Eventing Framework And Subscriptions](./reference/architecture/eventing-framework-and-subscriptions/eventing-framework-and-subscriptions.md) | Publisher/subscriber system, inotify, BPF, FSEvents, ETW |
| [Extensions And IPC](./reference/architecture/extensions-and-ipc/extensions-and-ipc.md) | Apache Thrift IPC, runtime plugin model, UUID routing |
| [Distributed Querying](./reference/architecture/distributed-querying/distributed-querying.md) | Remote SQL orchestration, TLS transport, fleet denylisting |
| [Remote HTTP Client](./reference/architecture/remote-http-client/remote-http-client.md) | Boost.Asio/Beast HTTPS client, TLS handshake, peer verification |
| [Logging And Query Observability](./reference/architecture/logging-and-query-observability/logging-and-query-observability.md) | Differential result tracking, JSON serialization, pluggable backends |
| [Database And Storage Plugins](./reference/architecture/database-and-storage-plugins/database-and-storage-plugins.md) | RocksDB persistent backend, ephemeral in-memory store, key-value interface |
| [Filesystem And Path Utilities](./reference/architecture/filesystem-and-path-utilities/filesystem-and-path-utilities.md) | Cross-platform file abstraction, glob resolution, permission enforcement |
|--------|-------------|
| [Filesystem And Fileops](./reference/architecture/filesystem-and-fileops/filesystem-and-fileops.md) | Cross-platform file abstraction, stat normalization, globbing, socket lifecycle |
| [Hashing](./reference/architecture/hashing/hashing.md) | Streaming hash computation, multi-algorithm support (MD5, SHA1, SHA256) |
| [Process And Profiler](./reference/architecture/process-and-profiler/process-and-profiler.md) | Worker and extension spawning, POSIX signal handling, code profiler |
| [System Utilities](./reference/architecture/system-utilities/system-utilities.md) | `EnumClassHash`, time conversion utilities |

---

## 🗺 Architecture Diagrams
## 🗺️ Architecture Diagrams

Visual Mermaid diagrams for each subsystem are available in:
Visual architecture documentation is available as Mermaid diagram files in the diagrams directory:

```text
docs/diagrams/architecture/
```

Diagrams cover all major subsystems including the SQL engine, eventing framework, configuration pipeline, distributed querying, OpenFrame auth layer, and more. Open any `.mmd` file in a Mermaid-compatible viewer.
Diagrams cover all major modules including:

- System overview and end-to-end data flow (`README.mmd`)
- Core Init And Runtime boot flow (`core-init-and-runtime.mmd`)
- SQL Core And Virtual Tables execution (`sql-core-and-virtual-tables.mmd`)
- Query Execution And Logging pipeline (`query-execution-and-logging.mmd`)
- Events Core publish/subscribe model (`events-core.mmd`)
- Distributed Querying orchestration (`distributed-querying.mmd`)
- Extensions Framework IPC (`extensions-framework.mmd`)
- Config And Packs lifecycle (`config-and-packs.mmd`)
- Database Backends storage layer (`database-backends.mmd`)
- Remote HTTP Client transport (`remote-http-client.mmd`)
- Hashing module (`hashing.mmd`)
- Filesystem And Fileops (`filesystem-and-fileops.mmd`)
- Process And Profiler (`process-and-profiler.mmd`)
- Plugin Interfaces And Logging (`plugin-interfaces-and-logging.mmd`)
- Config Plugins (`config-plugins.mmd`)
- System Utilities (`system-utilities.mmd`)

---

## 🔗 Quick Links

| Resource | Link |
|---|---|
| [Project README](../README.md) | Main project overview, quick start, and features |
| [Contributing Guide](../CONTRIBUTING.md) | How to contribute code, docs, and virtual tables |
| [License](../LICENSE.md) | License information |

---

## 💬 Community

> We do **not** use GitHub Issues or GitHub Discussions. All support and collaboration happens on **OpenMSP Slack**.

| Resource | Link |
|---|---|
| OpenMSP Community Slack | [Join here](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) |
| OpenMSP Website | [https://www.openmsp.ai/](https://www.openmsp.ai/) |
| OpenFrame Platform | [https://openframe.ai](https://openframe.ai) |
| Flamingo | [https://flamingo.run](https://flamingo.run) |
|----------|------|
| [Project README](../README.md) | Main project overview, quick start, and feature summary |
| [Contributing Guide](../CONTRIBUTING.md) | How to contribute — code style, branches, commits, PR process |
| [OpenMSP Slack](https://join.slack.com/t/openmsp/shared_invite/zt-36bl7mx0h-3~U2nFH6nqHqoTPXMaHEHA) | Community discussion and support (no GitHub Issues) |
| [openmsp.ai](https://www.openmsp.ai/) | OpenMSP community website |
| [flamingo.run](https://flamingo.run) | Flamingo MSP platform |
| [openframe.ai](https://openframe.ai) | OpenFrame unified MSP platform |

---

Expand Down
Loading
Loading