Brand Principles#

Brand Principles are the core values and conventions that guide the development of the opnDossier project, an open-source network analysis tool for OPNsense firewalls. These principles are codified in the AGENTS.md file and establish the project's design philosophy, development standards, and commitment to operator-focused tooling for security-critical environments.

The brand principles consist of five core values that shape every aspect of the project, from architectural decisions to code quality standards. These principles are complemented by comprehensive development conventions covering documentation, testing, security, and code review processes. Together, they create a cohesive framework that ensures opnDossier remains a trustworthy, high-quality tool for network operators working in airgapped and security-sensitive environments.

The principles reflect EvilBit Labs' commitment to building professional-grade tools that respect operator expertise, prioritize quality over feature proliferation, and maintain ethical standards in software development. They serve as both a technical guide for contributors and a public commitment to users about the project's values and priorities.

The Five Brand Principles#

The EvilBit Labs Brand Principles section in AGENTS.md defines five core values that guide all project decisions:

1. Trust the Operator#

"Full control, no black boxes"

This principle establishes that opnDossier must provide complete transparency and control to network operators. Every process, output format, and operational decision must be clear and predictable. The tool avoids hidden behaviors, undocumented side effects, or opaque processing that might undermine operator confidence.

Implementation of this principle includes transparent data transformations, clear output formats, and comprehensive documentation of all behaviors. The project provides explicit control over configuration options, report content, and data processing workflows. Operators can inspect, verify, and understand exactly what the tool does with their sensitive network configuration data.

This principle aligns with the operator-focused design philosophy documented in the core project philosophy: "Build tools for operators, by operators. Intuitive and efficient workflows."

2. Polish Over Scale#

"Quality over feature-bloat"

Rather than pursuing extensive feature sets, opnDossier prioritizes exceptional quality in its core functionality. This principle drives rigorous testing standards, careful code review, and thoughtful feature selection. The project maintains a focused scope while ensuring each capability meets high standards for reliability, performance, and maintainability.

The project enforces a minimum 85% test coverage threshold, exceeding the industry-standard 80% benchmark. All tests run with race detection enabled to catch concurrency issues. The project employs over 70 enabled linters in golangci-lint configuration to maintain code quality standards.

The "Polish Over Scale" principle also manifests in the zero tolerance for tech debt policy: "Never dismiss warnings, lint failures, or CI errors as 'pre-existing' or 'not from our changes.' If CI fails, investigate and fix it — regardless of when the issue was introduced."

3. Offline First#

"Built for where the internet isn't"

opnDossier is designed to operate in fully airgapped and offline environments where internet connectivity is unavailable or prohibited for security reasons. This principle ensures the tool has no external dependencies at runtime, does not perform network calls, and includes no telemetry or analytics that would require connectivity.

The project architecture explicitly targets airgapped, secure environments, making it suitable for deployment in high-security facilities, classified networks, and isolated operational environments. All functionality—from configuration parsing to report generation to compliance auditing—operates entirely on local data without external dependencies.

This principle extends to the development and distribution pipeline. The project uses SLSA Level 3 provenance attestation and Cosign keyless signing to enable secure, verifiable offline installation while maintaining supply chain security guarantees.

4. Sane Defaults#

"Clean outputs, CLI help that's actually helpful"

opnDossier provides sensible default configurations that work well for most use cases without requiring extensive customization. The CLI interface features comprehensive help text, clear error messages, and intuitive command structures. Output formats are clean and readable by default, with options for customization when needed.

The project implements custom help templates using the charmbracelet/fang framework to enhance CLI usability. Default report formats emphasize clarity and structure, making them immediately useful without configuration. Configuration options like emoji usage are configurable via the EnableEmojis field to accommodate different terminal environments and operator preferences.

The principle of sane defaults reduces friction for new users while providing flexibility for experienced operators who need specialized configurations.

5. Ethical Constraints#

"No dark patterns, spyware, or telemetry"

This principle establishes firm ethical boundaries for the project. opnDossier contains no telemetry, analytics, or data collection mechanisms. It employs no dark patterns—deceptive user interface designs that trick users into unintended actions. The project respects user privacy and data sovereignty completely.

Ethical constraints align with comprehensive supply chain security practices including SLSA attestation, reproducible builds, and transparent security processes. The project implements severity-based vulnerability blocking thresholds that block medium-severity issues on the main branch and high-severity issues on feature branches.

The principle extends to licensing and contribution processes. The project uses Developer Certificate of Origin (DCO) sign-off requirements to ensure legal clarity about code provenance without requiring copyright assignment that might complicate contributor rights.

Supporting Development Conventions#

Beyond the five core brand principles, AGENTS.md codifies comprehensive development standards that support the brand vision. These conventions ensure consistent code quality, maintainability, and contributor experience.

Documentation as First-Class Engineering#

All exported functions, types, and packages require comprehensive GoDoc comments. Documentation must consist of complete sentences with proper punctuation, with the godot linter enforcing punctuation standards. Comments should explain "why" decisions were made rather than merely describing "what" the code does.

PR #241 achieved 100% GoDoc coverage across all exported symbols, demonstrating the project's commitment to documentation excellence. This effort ensures every public API is documented with clear explanations suitable for both human readers and automated documentation tools.

Naming Conventions and Code Clarity#

The project follows standard Go naming conventions with exported identifiers using PascalCase and unexported identifiers using camelCase. Package names should be lowercase and single-word when possible. The revive linter prevents package name stuttering—patterns like compliance.CompliancePlugin are flagged in favor of cleaner names like compliance.Plugin.

These conventions reduce cognitive load and maintain consistency across the large codebase, making it easier for new contributors to understand and modify code.

Developer Certificate of Origin (DCO)#

All commits must be signed off using git commit -s, providing legal certification that contributors have the right to submit the code under the project's open source license. DCO enforcement is automated through a GitHub App that blocks merge of unsigned commits.

This approach provides legal clarity about code provenance while maintaining a lightweight contribution process that respects contributor rights more than traditional copyright assignment models.

Conventional Commits#

All commit messages must follow the Conventional Commits specification with the format <type>(<scope>): <description>. Valid scopes include parser, converter, audit, cli, model, plugin, builder, and schema. This structure enables automated changelog generation, semantic versioning, and clear communication about the nature of changes.

Linter Directive Placement#

//nolint directives must be placed on separate lines above code, never inline, because the gofumpt formatter strips inline comments during formatting. Every linter suppression must include a justification comment explaining why the suppression is safe and necessary.

This convention ensures that linter suppressions are deliberate, documented decisions rather than shortcuts that hide code quality issues.

Pre-commit Validation#

The .pre-commit-config.yaml file enforces comprehensive validation before commits are accepted. This includes file format validation for JSON, YAML, XML, and TOML; markdown formatting with over 10 plugins for GitHub Flavored Markdown, admonitions, and footnotes; line ending normalization; and GitHub Actions workflow validation via actionlint.

Pre-commit hooks provide immediate feedback on quality issues, allowing developers to fix problems before they enter version control rather than discovering them later in CI.

Test Coverage and Quality Standards#

The project maintains minimum 85% test coverage across all packages, exceeding the standard 80% industry threshold. All tests run with race detection enabled (go test -race) to catch concurrency bugs that might otherwise manifest only in production.

High test coverage ensures that code behavior is verified and documented through executable specifications, reducing regression risks and making refactoring safer.

Security-First Practices#

The project implements severity-based blocking thresholds for vulnerabilities: the main branch blocks medium-severity issues or higher, while feature branches block high-severity issues or higher. Developers are required to fix pre-existing issues encountered during work rather than dismissing them as out of scope.

This proactive approach to security ensures that the codebase continuously improves and that security issues are addressed promptly rather than accumulating as technical debt.

Enforcement Mechanisms#

The brand principles and development conventions are enforced through multiple layers of automated quality gates that provide consistent feedback to contributors:

Multi-Layer Quality Gates#

1. Pre-commit hooks - Format validation and structural checks run before commits are accepted, catching issues at the earliest possible point
2. Local development tools - The just task runner provides commands like just check, just lint, and just ci-check that mirror CI behavior locally
3. CI/CD pipeline - Linting failures block all downstream jobs; the just ci-check command combines pre-commit hooks, format checking, linting, unit tests, and integration tests
4. Static analysis - golangci-lint with over 70 enabled linters enforces code quality standards including documentation and naming conventions

Local/CI Parity#

The project implements strict local/CI parity, ensuring quality checks behave identically in development and continuous integration environments. Developers can run just ci-check locally to validate all changes before pushing code, identifying and fixing issues before CI runs rather than discovering them after.

This approach reduces iteration time and frustration by providing immediate feedback on quality issues.

Code Review Integration#

CodeRabbit AI performs automated code review using 15+ analysis tools, and contributors must acknowledge findings before merge. All pull requests must satisfy a 9-point checklist including linter compliance, format checks, test coverage, security gates, and DCO sign-off.

These automated reviews supplement human code review, catching common issues and allowing human reviewers to focus on higher-level design and correctness concerns.

Why These Principles Matter#

Professionalism and Operator Trust#

Network operators working with firewall configurations handle sensitive security infrastructure. The operator-focused design philosophy requires that tools used in these environments present a consistent, trustworthy brand through all artifacts. The "Trust the Operator" principle ensures transparency in all operations, building confidence that the tool behaves predictably and safely with sensitive network data.

Airgapped Compatibility#

Many high-security environments operate in airgapped configurations where internet connectivity is unavailable or prohibited. The tool is designed for these airgapped, secure environments, with the "Offline First" principle ensuring no external dependencies, no telemetry, and no network calls. This makes opnDossier suitable for deployment in classified networks, secure facilities, and isolated operational environments where traditional cloud-connected tools cannot be used.

Supply Chain Security#

The project implements comprehensive supply chain security including SLSA Level 3 provenance attestation, Cosign keyless signing, and Software Bill of Materials (SBOM) generation. The "Ethical Constraints" principle reinforces the security-first culture, demonstrating institutional maturity to operators and security teams. Organizations can verify the integrity and provenance of opnDossier binaries, ensuring they come from trusted sources without tampering.

Contributor Onboarding and Scalability#

Explicit, enforced conventions reduce ambiguity and friction when onboarding new contributors. The "Polish Over Scale" principle ensures a high-quality, maintainable codebase that remains comprehensible as it grows. The just install command automatically installs pre-commit hooks, providing immediate feedback on conventions rather than requiring manual learning of project standards.

Implementation for Contributors#

Contributors implementing features or fixes should follow these steps to ensure compliance with brand principles:

1. Run just install - Installs pre-commit hooks that validate commits against brand standards automatically
2. Run just check - Executes all pre-commit validation checks before pushing code to ensure compliance
3. Run just lint - Validates naming conventions, documentation standards, and code quality requirements
4. Review AGENTS.md - Reference the authoritative AGENTS.md file for project-specific coding standards and conventions
5. Commit with DCO sign-off - Use git commit -s to sign off all commits with Developer Certificate of Origin

These tools provide immediate feedback on compliance issues, allowing contributors to address problems locally before submitting pull requests.

Relevant Code Files#

Related Topics#

• Code quality standards and linting practices - Static analysis tools and quality gates that enforce code standards
• Supply chain security and SLSA compliance - Provenance attestation, signing, and SBOM generation
• Developer experience and tooling automation - Task runners, pre-commit hooks, and local CI parity
• Open source contribution guidelines - DCO requirements, commit message conventions, and PR processes
• Documentation practices and GoDoc standards - Comment conventions, documentation coverage, and API documentation
• Operator-focused design philosophy - User experience principles for professional network operators
• Security-first development in airgapped environments - Offline-capable tooling for high-security deployments