SOC Vault Builder

Build and operate a retrieval-first Obsidian Vault for SOC work (IR, DFIR, Threat Hunting, CTI) plus general notes and projects.

Repo layout (hybrid: logic in .py, content in editable .md)

OpenVault/
  build_vault.py            thin orchestrator (run once to build a Vault)
  vault_core.py             the runtime; installed into the Vault as vault.py
  vaultbuilder/             build logic (no content lives here)
    structure.py            FOLDER_TREE + folder builder
    assets_io.py            reads assets/ and writes them into the Vault
    install.py              installs runtime + modules into the Vault
    skill.py                generates SKILL.md from the installed modules
  assets/                   ALL content, as plain markdown you can edit freely
    templates/*.md
    mocs/*.md
    dashboards/*.md
    runbooks/*.md
    docs/{README,ARCHITECTURE,AGENT-GUIDE}.md
  modules_src/              runtime modules, copied into the Vault on init
    _common.py  case.py  note.py  project.py
  README.md

The split means: to change a template, a dashboard query, or the architecture doc, edit the .md in assets/ and re-run init. No Python edits needed.

Stage 1: bootstrap (run once)

python3 build_vault.py --target "/path/to/SOCVault"

Builds the folder tree, copies all assets/ content (rendering the {date} placeholder), installs the runtime and modules into 06-SYSTEM/scripts/, and generates 06-SYSTEM/skills/SKILL.md from the installed modules.

Paths with spaces are handled (quotes and shell-escaped spaces are stripped).

Stage 2: daily use (runtime inside the Vault)

The runtime autodetects the Vault from its own location, so you never pass the Vault path.

python3 /path/SOCVault/06-SYSTEM/scripts/vault.py --list
python3 .../vault.py case --discipline ir --name incident1234 --analyst jdoe --severity critical
python3 .../vault.py note --kind daily
python3 .../vault.py project --name "Rules Migration" --owner jdoe --priority high

Interactive when run without params at a terminal; non-blocking (uses params + defaults) when run by an agent or with stdin redirected.

Agent integration (OpenCode + Ollama)

Two layers, both derived from the actual module set so they never drift:

1. Static cheat-sheet for context loading: 06-SYSTEM/skills/SKILL.md. Load it into the agent so a local model knows which command to run for each intent, with worked examples. Good for models with weak tool calling.
2. Live schema for precise calls: python3 .../vault.py --describe returns JSON describing every module and parameter. The SKILL points the agent here as the source of truth.

Recommended flow for OpenCode/Ollama: load SKILL.md as context; the model picks the command and asks the user only for the parameters it declares; it then runs vault.py <module> --<param> <value>.

Editing content

• Templates: assets/templates/*.md. Every template carries format: template so dashboards exclude them (all dashboard Dataview queries filter format != "template").
• Dashboards / MOCs / runbooks: assets/dashboards|mocs|runbooks/*.md.
• Docs: assets/docs/*.md.
• Use {date} anywhere; it is replaced with today's date at build time.

Adding a module

Drop a .py into modules_src/ that defines a MODULE dict (name, summary, params with name/required/default/choices/prompt) and a run(vault_root, params) function returning a message. Re-run init: it is installed, discovered by the runtime automatically, and included in the regenerated SKILL.md. No edits to vault.py or build_vault.py needed.

Conventions

• English, ASCII names. No emojis, no long dashes; use -> and <-.
• Notes: YYYY-MM-DD-[TYPE]-[TOPIC].md. Cases: folders YYYY-MM-DD-<discipline>-<slug>/.
• Frontmatter is standardized by the modules; note bodies are free-form.
• Incidents live in 03-AREAS/.../incident-response and move by status (active -> closed -> archive after 12 months). See the runbooks.