OSSF Quality Standards#

OSSF Quality Standards refer to the comprehensive security and quality requirements established by the Open Source Security Foundation (OpenSSF) for open source software projects. These standards provide a framework for ensuring software supply chain security, code quality, and project maintainability through the OpenSSF Best Practices Badge Program. The opnDossier project, developed by EvilBit Labs, implements these standards through the EvilBit Labs Pipeline v2 Specification, achieving a passing OSSF Best Practices badge with comprehensive compliance across development, security, and release processes.

OSSF Quality Standards encompass multiple dimensions of software development practices including developer contribution verification through Developer Certificate of Origin (DCO), continuous integration and testing requirements, security vulnerability management, supply chain security through SLSA (Supply-chain Levels for Software Artifacts), and artifact signing using Sigstore Cosign. The opnDossier implementation demonstrates how these standards can be systematically applied to a Go-based open source project, providing a reference implementation for projects seeking OSSF compliance.

This article documents the specific implementation of OSSF Quality Standards in the opnDossier project, covering enforcement mechanisms, tooling, workflows, and governance structures. The implementation serves as a practical guide for software engineering teams implementing similar quality and security standards in their own projects.

OSSF Best Practices Badge and Scorecard#

The opnDossier project maintains compliance with OSSF Best Practices through automated weekly assessments and continuous monitoring. The OSSF Scorecard workflow runs every Saturday at 08:32 UTC using the ossf/scorecard-action@v2.4.3, providing comprehensive security health metrics for the repository.

The Scorecard assessment evaluates multiple dimensions of repository security and maintenance practices:

• Branch Protection: Enforcement of review requirements, status checks, and commit signing
• Code Review Practices: Verification that all changes undergo review before merge
• CI/CD Test Coverage: Validation of automated testing in continuous integration
• Dependency Update Practices: Assessment of regular dependency maintenance through Dependabot
• Vulnerability Disclosure: Evaluation of security reporting procedures and response mechanisms

Results from the Scorecard assessment are uploaded to the GitHub Security tab in SARIF (Static Analysis Results Interchange Format) and published to the OpenSSF REST API for public transparency. Scorecard artifacts are retained for 5 days, providing a historical view of security posture changes. This automated assessment provides objective, third-party validation of the project's adherence to security best practices.

Developer Certificate of Origin Enforcement#

The opnDossier project enforces the Developer Certificate of Origin (DCO) on all commits through automated GitHub App integration. DCO enforcement ensures that all contributors legally certify their right to submit code and agree to license terms, providing legal protection for the project and its users.

The DCO GitHub App automatically validates every commit in pull requests, requiring contributors to sign off their work using the git commit -s command. This adds a Signed-off-by: Your Name <your.email@example.com> trailer to each commit message, constituting the contributor's certification under the DCO terms. The enforcement is documented in CONTRIBUTING.md lines 729-748 and AGENTS.md line 865.

Pull requests with unsigned commits are automatically blocked from merging until all commits carry the required DCO sign-off. This strict enforcement ensures 100% compliance with contribution licensing requirements, eliminating ambiguity about code provenance and licensing. The DCO requirement is clearly communicated in project documentation and enforced at the technical level, making non-compliance impossible.

CI/CD Quality Gates#

The opnDossier project implements comprehensive quality gates in its continuous integration pipeline, ensuring that all code changes meet strict quality, format, and testing standards before merge. These gates provide automated enforcement of coding standards and prevent quality regressions.

Linting and Static Analysis#

The project uses a comprehensive golangci-lint configuration spanning 247 lines and enabling over 70 individual linters. This configuration enforces multiple categories of code quality:

Security Analysis: The gosec linter identifies security vulnerabilities including the G115 unsafe integer conversion checks, while errcheck ensures all errors are properly handled and staticcheck catches subtle bugs and performance issues.

Code Quality: Linters including revive, gocritic, and gocognit enforce code maintainability standards. The cyclop linter enforces a maximum cyclomatic complexity of 50, while funlen limits function length to maintain readability.

Code Style: Format enforcement uses gofumpt (stricter than standard gofmt), goimports for import management, gci for import ordering, and golines with a maximum line length of 120 characters.

Concurrency Safety: Specialized linters including intrange, fatcontext, and copyloopvar catch common concurrency pitfalls in Go code.

Error Handling: The errorlint, errchkjson, and nilerr linters ensure consistent and correct error handling patterns throughout the codebase.

The CI workflow runs golangci-lint v2.9 on every push and pull request. Developers can run the same checks locally using the just lint command, ensuring parity between local development and CI environments.

Format Checking#

Format validation runs as both a pre-commit hook and CI check, enforcing consistent code formatting across all contributors. The gofumpt tool provides stricter formatting than standard gofmt, while goimports automatically manages import statements. Format violations cause CI builds to fail, and developers can fix issues using the just format command.

Test Coverage and Quality#

The opnDossier project enforces an 85% minimum test coverage threshold, exceeding the 80% threshold documented in CONTRIBUTING.md. All tests run with race detection enabled through the go test -race flag, catching data races and concurrency bugs that might otherwise only manifest in production.

The CI workflow executes tests across multiple platforms (Ubuntu, macOS, Windows) to ensure cross-platform compatibility. Integration tests run with a 5-minute timeout to verify end-to-end functionality. Coverage reports are uploaded to Codecov for tracking and trend analysis, providing visibility into coverage changes over time.

Developers can validate their changes locally using just test for the basic test suite or just test-coverage for detailed coverage reports. This local/CI parity ensures that developers can catch issues before pushing code.

Security Analysis and Vulnerability Management#

The opnDossier project implements a multi-layered security scanning approach combining automated tools, scheduled assessments, and clear vulnerability response procedures.

OSSF Scorecard Security Assessment#

The weekly OSSF Scorecard scans provide continuous security health monitoring, uploading SARIF results to the GitHub Security tab. This provides centralized visibility into security findings alongside other code scanning results.

Software Bill of Materials (SBOM)#

The project generates comprehensive SBOMs in multiple formats for transparency and supply chain security. The CI workflow generates CycloneDX SBOMs for both the compiled binary and Go modules on every build. A weekly scheduled SBOM workflow runs every Sunday at midnight UTC, generating fresh SBOMs with 90-day artifact retention.

SBOMs enable security teams to quickly assess dependency exposure during vulnerability disclosures and support compliance requirements for software transparency. Developers can generate SBOMs locally using the just sbom command.

Dependency Scanning#

The project uses Dependabot for automated dependency vulnerability detection and updates. Dependabot scans four categories weekly:

• Go modules (go.mod and go.sum)
• GitHub Actions workflows
• Docker images
• Dev Container configurations

When Dependabot identifies outdated dependencies or security vulnerabilities, it automatically creates pull requests with upgrade recommendations, enabling rapid response to supply chain vulnerabilities.

License Compliance#

The FOSSA configuration enables automated license scanning for Go dependencies. FOSSA integration through the GitHub App enforces license policy compliance, ensuring all dependencies use compatible licenses. This prevents inadvertent inclusion of dependencies with incompatible or restrictive licenses.

Vulnerability Scanning and Response#

The project's security scanning strategy combines multiple tools documented in the security procedures. While Grype and Snyk scanning are extensively documented in project security files, the verified implementation relies on OSSF Scorecard, Dependabot, FOSSA, and local security scanning via gosec (executed with just scan).

The SECURITY.md file documents comprehensive security features including memory-safe Go implementation, XXE-safe XML parsing, and offline-first design principles that minimize attack surface.

Vulnerability Reporting and Response#

The opnDossier project maintains a structured vulnerability reporting process with clear timelines and communication channels. Security vulnerabilities must be reported privately through GitHub Security Advisories or via email to support@evilbitlabs.io. Public disclosure through GitHub Issues is explicitly prohibited to prevent premature exposure.

The security contact, @UncleSp1d3r, maintains responsibility for triaging reports. The response timeline specifies:

• 1 week: Initial acknowledgment of vulnerability report
• 2 weeks: Completed security assessment and triage
• 90 days: Target fix timeline for medium and higher severity vulnerabilities

The project provides a PGP key for encrypted vulnerability reports, ensuring confidentiality for sensitive disclosures. Supported versions currently include 1.1.x and 1.2.x releases.

Severity-Based Response Matrix#

The project implements comprehensive security scanning through multiple tools. The security workflow (govulncheck, CodeQL, Trivy) runs on every pull request, every push to main, and weekly. Trivy filesystem scanning reports CRITICAL, HIGH, and MEDIUM findings, with the ignore-unfixed option enabled to reduce noise from unpatched vulnerabilities.

The project targets a 90-day response timeline for medium and higher severity vulnerabilities, balancing security with development velocity.

API Documentation Standards#

The opnDossier project enforces comprehensive API documentation requirements for all exported code, ensuring that users and contributors can understand functionality without reading implementation details. These standards align with the Google Go Style Guide and Go community best practices.

Documentation Requirements#

AGENTS.md specifies that all exported functions, types, and packages must include GoDoc comments. Package-level documentation appears at the top of package files, providing context and usage guidance. Function documentation uses imperative mood and clearly describes functionality, parameters, return values, and any important behavior or edge cases.

Documentation should provide practical context rather than simply restating function signatures. Examples should be included for complex functionality, demonstrating typical usage patterns. The project emphasizes clarity and completeness over brevity.

Code Quality Practices#

Beyond documentation, the project enforces additional code quality standards:

Method Naming: Functions and methods use descriptive names that explicitly indicate functionality, avoiding ambiguous or generic names.

Type Safety: Code uses specific types rather than interface{} where possible, leveraging Go's type system for compile-time safety.

Error Handling: All errors must be checked and handled appropriately, with no ignored error returns.

Library Code Constraints: Library code must not use panic() for error handling, must validate all input, and must never ignore errors. These constraints ensure that library code behaves predictably and doesn't cause unexpected application crashes.

Release Management and Versioning#

The opnDossier project implements automated, reproducible releases with comprehensive artifact signing and verification. The release process balances automation with human oversight, ensuring quality while minimizing manual effort.

Semantic Versioning#

All releases follow Semantic Versioning (SemVer) with the format vMAJOR.MINOR.PATCH:

• MAJOR: Incremented for incompatible API changes or breaking changes
• MINOR: Incremented for new backwards-compatible features
• PATCH: Incremented for backwards-compatible bug fixes

Pre-release versions use suffixes like v2.0.0-rc1 for release candidates or v2.0.0-beta1 for beta releases. This versioning scheme provides clear communication about compatibility and change impact.

GoReleaser Automation#

The GoReleaser configuration, spanning 342 lines, orchestrates multi-platform release builds with comprehensive artifact generation:

Binary Builds: Cross-compilation produces binaries for FreeBSD, Linux, macOS (including universal binaries for both Intel and Apple Silicon), and Windows, each for amd64 and arm64 architectures.

Native Packages: The build produces distribution-specific packages including .deb (Debian/Ubuntu), .rpm (Red Hat/Fedora), .apk (Alpine), and .pkg.tar.xz (Arch Linux). Each package includes man pages and shell completions for bash, zsh, fish, and PowerShell.

Container Images: Docker images are pushed to ghcr.io/evilbit-labs/opndossier with multiple tags including version-specific tags and the latest tag.

Checksums: The build generates opnDossier_checksums.txt containing cryptographic hashes of all artifacts for integrity verification.

Reproducible Builds: Configuration includes mod_timestamp: "{{ .CommitTimestamp }}" and CGO_ENABLED=0, ensuring that builds are reproducible from the same source code regardless of build environment.

Homebrew Distribution: Automated integration with EvilBit-Labs/homebrew-tap provides macOS installation via Homebrew cask.

Automated Changelog Generation#

The project uses git-cliff to automatically generate human-readable release notes from conventional commits. Commits are categorized by type:

• feat: → Features section
• fix: → Bug Fixes section
• fix(security): → Security-specific fixes
• perf: → Performance improvements
• docs: → Documentation updates
• test:, ci:, chore:, revert: → Supporting changes

Developers review unreleased changes using just changelog-unreleased before creating releases, ensuring accurate and complete release notes.

Release Process Workflow#

The documented release process follows a systematic workflow:

1. Pre-release Validation: Run just ci-full to execute comprehensive checks including tests, linting, security scanning, and GoReleaser configuration validation.

2. Snapshot Testing: Execute just release-snapshot to build all artifacts locally without publishing, verifying build configuration.

3. Changelog Review: Run just changelog-unreleased to review changes since the last release, ensuring accurate release notes.

4. Version Tagging: Create an annotated git tag with git tag vX.Y.Z.

5. Authentication: Authenticate to container registry with echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin.

6. Release Execution: Run just release to trigger GoReleaser, which builds all artifacts, generates SBOMs, signs artifacts, and publishes to GitHub Releases and container registry.

7. Tag Publishing: Push the release tag with git push origin vX.Y.Z, triggering the release workflow.

This workflow ensures that only tested, validated code reaches users, while maintaining full automation for the build and distribution process.

Supply Chain Security#

The opnDossier project implements comprehensive supply chain security measures aligned with modern software supply chain security frameworks, providing cryptographic verification of build provenance and artifact integrity.

SLSA Level 3 Provenance#

The release workflow generates SLSA Level 3 provenance attestations for all release artifacts. Using actions/attest-build-provenance@v1, the workflow creates cryptographic proofs linking each artifact to the exact source code version, build environment, and build process that produced it.

These provenance attestations enable users to verify that artifacts were built from legitimate source code through legitimate build processes, detecting potential supply chain compromises. Users can verify artifacts using the slsa-verifier verify-artifact command, confirming the chain of custody from source to binary.

Cosign Artifact Signing#

All release artifacts undergo keyless signing using Sigstore Cosign, eliminating the operational burden and security risks of managing signing keys. The GoReleaser configuration executes cosign sign-blob --bundle=${signature} ${artifact} --yes for each artifact.

Keyless signing uses OIDC (OpenID Connect) authentication, binding signatures to the GitHub Actions identity that performed the build. This approach provides the security benefits of code signing without requiring private key management. The release workflow includes verification steps that validate checksum signatures and attestations before completing the release.

Signatures are distributed as bundle files containing in-toto attestations. Users verify artifacts using:

cosign verify-blob --bundle cosign.bundle opnDossier_checksums.txt

This verification confirms that the artifact was signed during an authorized GitHub Actions workflow execution from the legitimate repository.

SBOM Generation and Distribution#

The project generates SBOMs in multiple formats for different use cases. GoReleaser configuration uses cyclonedx-gomod to produce:

• CycloneDX JSON (sbom.cyclonedx.json): Optimized for dependency management tools and vulnerability scanning
• SPDX JSON (sbom.spdx.json): Standardized format for compliance and legal review

The weekly SBOM workflow generates fresh SBOMs every Sunday at midnight UTC, ensuring up-to-date dependency information is available even between releases. SBOMs are accessible from GitHub release artifacts and workflow runs, with 90-day retention for workflow artifacts.

Developers can generate SBOMs locally using just sbom, enabling proactive security analysis during development. The comprehensive SBOM generation supports security teams in rapidly assessing exposure during vulnerability disclosures and satisfies software transparency requirements for regulated environments.

Project-Specific Compliance Rules#

Beyond general OSSF standards, the opnDossier project enforces additional project-specific compliance rules that ensure code quality and maintainability.

Pre-commit Validation#

All commits undergo automated validation through pre-commit hooks that check:

• File Format Validation: JSON, YAML, and XML files must be well-formed and valid
• Markdown Formatting: Markdown files must follow consistent formatting enforced by mdformat
• Line Ending Normalization: Ensures consistent line endings across all files
• Large File Detection: Prevents accidental commit of large binary files
• Commit Message Validation: Enforces conventional commit format via commitlint

Developers run these checks using just check, with automatic installation of hooks via just install during environment setup.

Conventional Commit Standards#

All commits must follow the Conventional Commits specification with the format <type>(<scope>): <description>. Required scopes include:

• (parser): Parser functionality
• (converter): Format conversion logic
• (audit): Security auditing features
• (cli): Command-line interface
• (model): Data models and types
• (plugin): Plugin system
• (builder): Build utilities
• (schema): Schema definitions

Example commits:

feat(parser): add support for new XML schema
fix(config): resolve environment variable precedence
docs(readme): update configuration examples

This structured format enables automated changelog generation and provides clear communication about the nature and scope of changes.

Pull Request Quality Gates#

Every pull request must satisfy a 9-point checklist before merge:

1. ✅ All linters pass (golangci-lint)
2. ✅ Format checks pass (gofumpt, goimports)
3. ✅ All tests pass with race detection and ≥85% coverage
4. ✅ Coverage uploaded to Codecov
5. ✅ Security gates pass (OSSF Scorecard and documented scanning tools)
6. ✅ License compliance passes (FOSSA)
7. ✅ Valid Conventional Commits format
8. ✅ DCO sign-off on all commits
9. ✅ CodeRabbit.ai findings acknowledged

This comprehensive checklist ensures that merged code meets all quality, security, and legal requirements.

AI-Assisted Code Review#

The project uses CodeRabbit AI for automated code review, configured with 516 lines of path-specific instructions. CodeRabbit analyzes pull requests with an assertive profile and runs 15+ tools including:

• golangci-lint: Go code quality
• markdownlint: Markdown consistency
• gitleaks: Secret detection
• semgrep: Security pattern matching
• yamllint: YAML validation
• checkov: Infrastructure-as-code security
• actionlint: GitHub Actions workflow validation

Path-specific instructions ensure that reviews focus on relevant concerns for each code area (cmd, parser, validator, model, converter, audit, display). Contributors must acknowledge CodeRabbit findings before merge.

Local Development Parity#

The justfile (456 lines, 50+ tasks) enables developers to run all CI checks locally:

just test # Run tests with coverage
just lint # Run linters
just check # Run pre-commit checks
just ci-check # Full CI validation
just scan # Vulnerability scanning (gosec)
just sbom # Generate SBOM artifacts
just security-all # All security checks

This local/CI parity enables developers to identify and fix issues before pushing code, reducing CI failures and accelerating development cycles.

Project Governance and Security Response#

The opnDossier project operates under a maintainer-driven governance model with clear responsibilities and decision-making processes.

Governance Structure#

Maintainer: @UncleSp1d3r holds responsibility for merging pull requests, managing releases, setting project direction, and reviewing security reports.

Security Contact: support@evilbitlabs.io serves as the official security contact for vulnerability reports and security coordination.

Contributors: Any individual following contribution guidelines can submit issues, pull requests, and participate in project discussions.

Decision-Making Framework#

The project uses a tiered decision-making approach based on change impact:

• Bug fixes and minor changes: Any maintainer can review and merge after CI passes
• New features: Require discussion in a GitHub issue before implementation, with maintainer approval required for merge
• Architecture changes: Require maintainer approval with documented rationale explaining the architectural decision
• Breaking changes: Require discussion with community input to assess impact, with final maintainer approval
• Releases: Any maintainer can prepare releases following the documented release process, with GoReleaser handling automation

This framework balances agility for routine changes with appropriate oversight for significant modifications.

Security Continuity#

The project implements several measures to ensure security continuity:

• Organizational Redundancy: The GitHub organization (EvilBit-Labs) has multiple administrators, preventing single points of failure
• Process Automation: All CI/CD pipelines are fully automated through GitHub Actions and GoReleaser, with comprehensive documentation
• Standards Documentation: Security and development standards are documented in AGENTS.md, CONTRIBUTING.md, and SECURITY.md
• Keyless Signing: Release signing uses Sigstore keyless signatures, eliminating personal key dependencies

These measures ensure that the project can continue operating and maintaining security standards even if key personnel become unavailable.

Development Environment Setup#

Setting up a development environment for opnDossier contributions requires several prerequisite tools and follows a standardized setup process.

Prerequisites#

• Go: Version 1.26 or later (latest stable recommended)
• just: Task runner for development workflows (installation instructions)
• git: Version control with GPG signing configured
• golangci-lint: Latest version for comprehensive linting (installation instructions)

Initial Setup#

Clone the repository and run the initialization script:

git clone https://github.com/EvilBit-Labs/opnDossier.git
cd opnDossier
just install # Install dependencies and pre-commit hooks
just check # Verify setup
just test # Run full test suite

The just install command automatically installs pre-commit hooks that validate commits before they are created. The verification workflow ensures that all tools are properly configured and the development environment is ready for contributions.

Development Workflow#

A typical development session follows this pattern:

# Create a feature branch
git checkout -b feat/my-feature

# Make changes and run quality checks
just check # Pre-commit validation
just lint # Linting
just test # Tests with coverage

# Commit with DCO sign-off
git commit -s -m "feat(parser): add new feature"

# Run full CI validation before pushing
just ci-check

# Push changes
git push origin feat/my-feature

This workflow ensures that all quality gates pass before code reaches CI, reducing iteration time and CI resource consumption.

Usage Examples#

Developer Workflow#

# Clone repository and setup
git clone https://github.com/EvilBit-Labs/opnDossier.git
cd opnDossier
just install

# Before committing changes
just check # Run pre-commit checks
just lint # Run linters
just test # Run tests with coverage
just ci-check # Full CI validation

# Commit with DCO sign-off
git commit -s -m "feat(parser): add new XML schema support"

# Security checks
just scan # Run gosec security scanner
just sbom # Generate SBOM
just security-all # All security checks

Release Workflow#

# Prepare release
just ci-full # Full compliance check
just release-snapshot # Test build without publishing
just changelog-unreleased # Review changes

# Create and push release
git tag v1.2.3
echo $GITHUB_TOKEN | docker login ghcr.io -u USERNAME --password-stdin
just release # Build, sign, and publish
git push origin v1.2.3

Verify Release Artifacts#

# Verify Cosign signature
cosign verify-blob \
  --bundle cosign.bundle \
  opnDossier_checksums.txt

# Verify SLSA provenance
slsa-verifier verify-artifact \
  --provenance-path provenance.intoto.jsonl \
  --source-uri github.com/EvilBit-Labs/opnDossier \
  opnDossier_linux_amd64

# Verify GitHub attestation
gh attestation verify opnDossier_checksums.txt \
  --owner EvilBit-Labs

Relevant Code Files#

Related Topics#

• OSSF Best Practices Badge - Criteria and assessment process for earning the OpenSSF Best Practices badge
• Developer Certificate of Origin - Legal framework for contributor certification
• SLSA Framework - Supply-chain Levels for Software Artifacts security framework
• Semantic Versioning - Version numbering scheme for APIs
• Conventional Commits - Structured commit message specification
• Sigstore Cosign - Keyless code signing infrastructure
• CycloneDX SBOM - Software Bill of Materials standard
• SPDX SBOM Standard - Software Package Data Exchange standard
• Google Go Style Guide - Go language coding conventions
• EvilBit Labs Pipeline v2 Specification - Reference specification for OSSF compliance implementation

See Also#

• OpenSSF Scorecard - Automated security assessment tool
• GoReleaser - Release automation for Go projects
• golangci-lint - Go linter aggregator
• git-cliff - Changelog generator from git history
• just - Command runner for project-specific tasks