Contributing Guidelines

GuardLink is open source and community-driven. Whether you're fixing a bug, improving documentation, adding a new annotation verb, or building a new output format — contributions of all sizes are welcome.

GitHub Repository Join Discord

Ways to Contribute

Code

Fix bugs, add commands, improve the parser, extend output formats, or add new LLM provider integrations.

Documentation

Improve annotation examples, write guides, add diagrams, or fix unclear explanations in the spec.

Bug Reports

Open a GitHub issue with a minimal reproduction. Include your Node.js version, OS, and the command that failed.

Language Support

Add or improve comment-style detection for languages not currently covered by the parser.

Getting Started

# 1. Fork and clone the repo

git clone https://github.com/Bugb-Technologies/guardlink.git

cd guardlink

# 2. Install dependencies

npm install

# 3. Build the project

npm run build

# 4. Link for local development

npm link

# 5. Run tests

npm test

Node.js18 or higher required

TypeScriptAll source files are .ts

OutputCompiled to dist/ via tsc

Pull Request Process

Open an issue first

For non-trivial changes, open a GitHub issue to discuss the approach before writing code. This avoids duplicate work and misaligned implementations.

Branch from main

Create a feature branch from main with a descriptive name like fix/parser-boundary-edge-case or feat/sarif-min-severity-filter.

Follow the code style

Match the patterns in adjacent files — TypeScript, no default any, explicit return types on public functions. Run npm run build to confirm no compiler errors.

Add GAL annotations

GuardLink annotates itself. If your PR adds or changes security-relevant code, add the appropriate @g.* annotations above the changed lines so the threat model stays accurate.

Write tests

Parser changes require tests covering the new syntax. Report and dashboard changes should include a snapshot or fixture that verifies the output shape.

Submit and respond

Open the PR against main with a clear description. Link the related issue. Respond to review feedback within a reasonable time to keep the PR moving.

Codebase Map

Understanding where things live helps you find the right place to make your change.

src/

cli/ — Command dispatch, argument parsing, all top-level commands

tui/ — Interactive terminal UI and slash command handlers

mcp/ — MCP server, tool definitions, resource handlers

parser/ — parse-project, parse-file, parse-line, validate, normalize, comment-strip

analyze/ — AI threat reports, framework prompts, LLM client, tools

dashboard/ — HTML dashboard generator, stats, heatmap, Mermaid diagrams

report/ — Markdown report and Mermaid diagram generation

analyzer/ — SARIF 2.1.0 export

diff/ — Git diff of threat models between refs

agents/ — Agent config, launcher, prompts for Claude/Cursor/Codex

init/ — guardlink init, templates, agent picker

types/ — ThreatModel and all shared TypeScript types

.guardlink/

definitions.ts — GuardLink's own @asset, @threat, @control declarations

Areas Looking for Help

GOOD FIRST ISSUES

Additional language comment-style detection (e.g. Kotlin, Swift, Dart)
Improving error messages for common annotation syntax mistakes
Adding new @threat and @control definitions to the built-in taxonomy
Extending the SARIF export with more metadata fields
Improving the TUI slash command autocomplete
Writing end-to-end tests for complex cross-repo workspace scenarios
New threat report framework prompts (e.g. LINDDUN for privacy threats)
Dashboard accessibility improvements (ARIA labels, keyboard navigation)

Spec & Language Changes

The GuardLink Annotation Language (GAL) is an open specification licensed under CC-BY-4.0. Changes to the annotation grammar, verb semantics, or ThreatModel schema affect all tooling that implements the spec — so they require a higher bar than implementation changes.

Adding a new verb

Open a discussion issue first. New verbs must have a clear security use case not covered by existing verbs, a defined argument grammar, and a corresponding ThreatModel schema field. Reference the docs/SPEC.md for the full grammar format.

Changing existing behavior

Breaking changes to parsing behavior or schema shape must be accompanied by a version bump and migration note in CHANGELOG.md. The spec version in metadata.schema_version must increment.

Code of Conduct

GuardLink follows the standard open source contributor expectations. Be respectful, assume good intent, and keep discussions focused on technical merit. Issues and pull requests are not the place for harassment or hostility. If something is unclear, ask in Discord before assuming bad faith.

License

Implementation (CLI)

The GuardLink CLI implementation is open source. See the LICENSE file in the repository for terms.

Specification (GAL)

The GuardLink Annotation Language specification is licensed under CC-BY-4.0 — free to read, implement, and build tooling against with attribution.

Get in Touch

The fastest way to get a question answered or get feedback on an idea before opening a PR is to jump into the Discord server.

Open an Issue Discord Community Open a Pull Request