Thank you for your interest in contributing to Vigil. This document covers how to get started, how to submit changes, and how to find things to work on.

Getting Started

Prerequisites

  • Python 3.10+
  • Node.js 18+
  • Docker Desktop (must be running)
  • Git with submodule support
  • Claude API key from console.anthropic.com

Local Setup

git clone --recurse-submodules https://github.com/Vigil-SOC/vigil.git
cd vigil
./start.sh

Access the frontend at http://localhost:6988 and the API at http://localhost:6987.

See the README for full setup instructions including manual install and Docker options.

How to Contribute

Fork and Pull Request Workflow

  1. Fork the repository to your GitHub account
  2. Clone your fork locally: 
    git clone --recurse-submodules https://github.com/YOUR-USERNAME/vigil.git
cd vigil
  3. Create a branch for your work: 
    git checkout -b feature/your-feature-name
  4. Make your changes and test them
  5. Commit with sign-off (required — see below): 
    git commit -s -m "Add new MCP integration for SentinelOne"
  6. Push to your fork: 
    git push origin feature/your-feature-name
  7. Open a Pull Request from your fork to Vigil-SOC/vigil:main

Sign-Off Requirement (DCO)

All commits must include a Signed-off-by line certifying you have the right to submit the code under Vigil’s Apache 2.0 license. This is the Developer Certificate of Origin.

Add it automatically with the -s flag:

git commit -s -m "Your commit message"

This adds a line like Signed-off-by: Your Name <your@email.com> using your git config identity. Configure it once:

git config user.name "Your Name"
git config user.email "your@email.com"

Versioning and Releases

Vigil follows Semantic Versioning. While in 0.x, minor version bumps may include breaking changes to agent prompts, workflow schemas, and MCP integration interfaces. Patch bumps are always backward compatible. See RELEASING.md for the full release process.

The Helm chart at infra/helm/vigil/ has two version fields: appVersion (the Vigil release the chart deploys) and chart version (the chart packaging version). release-please bumps both in lockstep on every release. See RELEASING.md for the rationale and the escape hatch for chart-only changes between app releases.

What to Work On

Good First Issues

Look for issues labeled good-first-issue — these are scoped, well-defined tasks suitable for new contributors.

Using the Auto-Contributor

Vigil includes a competitive research tool in contrib/auto-contributor/ that identifies capability gaps versus proprietary AI security platforms and generates contribution specifications. If you want to find meaningful work:

  1. Pick a proprietary AI SOC or security platform
  2. Run the auto-contributor skill to identify gaps
  3. The output includes ready-to-file GitHub issues with acceptance criteria

See contrib/README.md for details.

Contribution Areas

Contributions are welcome across all areas:

  • New MCP integrations — connect Vigil to additional security tools (EDR, SIEM, cloud, ticketing)
  • Agent improvements — enhance agent prompts, reasoning, or tool usage
  • New Workflows — define new multi-agent workflows in workflows/
  • Detection rules — add Sigma, Splunk, Elastic, or KQL rules
  • Bug fixes — check the issue tracker
  • Documentation — improve docs, add examples, fix errors
  • Tests — expand test coverage

Code Guidelines

Project Structure

vigil/
├── core/            # Shared library: capability domains + storage/platform tier
│   └── workflows/definitions/   # Multi-agent workflow definitions (WORKFLOW.md files)
├── services/        # Deployables only: api (FastAPI + Agent SDK), daemon
│                    #   (headless autonomous SOC), worker (ARQ llm-worker)
├── clients/web/     # React web client
├── contrib/         # Community development tools (not runtime)
├── infra/           # Docker Compose, Helm chart, DB init SQL
├── data/            # Schemas, registry, taxonomy
├── docs/            # Documentation
└── tests/           # Test suite

Style

flake8, black and isort gate CI over services/ and core/. Install the pinned toolchain and the hook that matches it once:

pip install -r requirements-dev.txt && pre-commit install

Pass the tools no arguments — setup.cfg is the only config, and pre-commit reads the same file, so formatting locally cannot produce a tree CI rejects. ./setup_dev.sh does both steps for you.

  • Python: follow existing patterns in core/. Use type hints. core/ must not import services/, and core/storage + core/platform must not import a capability domain — .importlinter gates both; run lint-imports locally.
  • TypeScript/React: follow existing patterns in clients/web/.
  • Workflows: follow the format of existing core/workflows/definitions/*/WORKFLOW.md files.
  • MCP servers: follow the patterns in tools/.

Testing

Run the test suite before submitting:

./tests/run-tests.sh

New features should include tests. Place them in tests/ following existing naming conventions.

Commit Messages

We prefer Conventional Commits so we can automate changelogs and version bumps via release-please (see RELEASING.md). It is not strictly enforced at the per-commit level — if your individual commits don’t match the format, please update your PR title to follow the convention before requesting review (since we squash-merge, the PR title becomes the commit on main). If you forget, a maintainer may adjust the title before merging. The DCO sign-off (git commit -s), however, is required on every commit.

The preferred format is:

<type>(<optional scope>): <short summary>

<optional body explaining what and why>

Signed-off-by: Your Name <your@email.com>

Common types:

  • feat: — a new feature (triggers a minor version bump)
  • fix: — a bug fix (triggers a patch bump)
  • docs: — documentation only
  • chore: — tooling, build, dependency bumps
  • refactor: — code change that neither fixes a bug nor adds a feature
  • test: — adding or fixing tests
  • perf: — performance improvement

Common scopes for Vigil: agents, workflows, mcp, frontend, daemon, helm, api, db.

Breaking changes: add ! after the type/scope (feat!:) or include BREAKING CHANGE: in the body.

Examples:

feat(mcp): add SentinelOne integration
fix(daemon): prevent double-processing of correlated alerts
docs(workflows): clarify threat-hunt phase ordering
chore(deps): bump fastapi to 0.110.0
feat(agents)!: rename Triage agent prompt schema

Pull Request Guidelines

  • One logical change per PR
  • Include tests for new functionality
  • Update relevant documentation
  • Reference related issues: “Closes #123” or “Part of #456”
  • Keep PRs reviewable — if a feature is large, break it into smaller PRs

Pull Request Titles

Because we squash-merge PRs, the PR title becomes the commit message on main — which is what release-please reads to decide version bumps and changelog entries. Setting a Conventional Commits-style PR title is the author’s responsibility (e.g., feat(mcp): add SentinelOne integration). You can update the title at any point before merge by editing the PR. If you forget, a maintainer may adjust it before merging, but please don’t rely on that.

Reporting a Security Vulnerability

Do not open a public issue or pull request for a security vulnerability. Report it privately through GitHub’s private vulnerability reporting or by email to security@deeptempo.ai. See SECURITY.md for scope, response targets, our coordinated disclosure window, and safe harbor.

Community

Join us on Discord to discuss ideas, get help, and collaborate.

License

By contributing to Vigil, you agree that your contributions will be licensed under the Apache 2.0 License.