If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/github/secure_headers shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across the board

• Last commit 1w ago
• 14 active contributors
• Distributed ownership (top contributor 23% of recent commits)
• MIT licensed
• CI configured
• Tests present

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live github/secure_headers repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/github/secure_headers.

What it runs against: a local clone of github/secure_headers — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in github/secure_headers | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 39 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of github/secure_headers. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/github/secure_headers.git
#   cd secure_headers
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of github/secure_headers and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "github/secure_headers(\\.git)?\\b" \\
  && ok "origin remote is github/secure_headers" \\
  || miss "origin remote is not github/secure_headers (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "lib/secure_headers.rb" \\
  && ok "lib/secure_headers.rb" \\
  || miss "missing critical file: lib/secure_headers.rb"
test -f "lib/secure_headers/configuration.rb" \\
  && ok "lib/secure_headers/configuration.rb" \\
  || miss "missing critical file: lib/secure_headers/configuration.rb"
test -f "lib/secure_headers/headers/content_security_policy.rb" \\
  && ok "lib/secure_headers/headers/content_security_policy.rb" \\
  || miss "missing critical file: lib/secure_headers/headers/content_security_policy.rb"
test -f "lib/secure_headers/middleware.rb" \\
  && ok "lib/secure_headers/middleware.rb" \\
  || miss "missing critical file: lib/secure_headers/middleware.rb"
test -f "lib/secure_headers/railtie.rb" \\
  && ok "lib/secure_headers/railtie.rb" \\
  || miss "missing critical file: lib/secure_headers/railtie.rb"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 39 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~9d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/github/secure_headers"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

secure_headers is a Ruby gem that automatically injects security HTTP response headers (CSP, HSTS, X-Frame-Options, etc.) into Rails/Sinatra applications with sensible defaults. It provides global config, per-request overrides, and rack middleware to enforce security policies like Content Security Policy 2, prevent clickjacking via X-Frame-Options, and mark cookies with Secure/HttpOnly/SameSite attributes—solving the problem of manually managing fragmented security headers across an application. Modular single-gem architecture: lib/secure_headers/headers/ contains individual header implementations (content_security_policy.rb, strict_transport_security.rb, etc.), lib/secure_headers/configuration.rb manages global and per-request config, lib/secure_headers/middleware.rb provides Rack integration, lib/secure_headers/railtie.rb hooks into Rails, and lib/secure_headers/utils/ handles utilities like cookies_config.rb.

Rails and Sinatra application developers who need to harden their web applications against XSS, clickjacking, mixed-content, and cookie vulnerabilities without manually crafting and maintaining security headers in each response.

Highly mature and production-ready. The repo is officially maintained by GitHub, actively developed on the 7.x line (main branch), has comprehensive CI/CD via GitHub Actions (.github/workflows/build.yml), extensive documentation across 7 upgrading guides, and follows semantic versioning with 196KB of Ruby code. The project is battle-tested in production at scale.

Very low risk. GitHub ownership provides strong maintenance guarantees, the codebase has no external gem dependencies (only dev dependencies), and the API is stable with clear upgrade paths documented (docs/upgrading-to-*.md for versions 4-7). The main risk is policy/spec changes in the HTTP security landscape requiring updates, which is mitigated by active maintenance.

The main branch is on 7.x line with recent migrations documented (docs/upgrading-to-7-0.md). Bug fixes are being backported to the 6.x branch. GitHub Dependabot is configured (.github/dependabot.yml) for automated dependency updates. The project uses GitHub Actions for build automation and releases.

git clone https://github.com/github/secure_headers.git && cd secure_headers && bundle install && bundle exec rspec

Daily commands: bundle exec rspec (full test suite) or bundle exec guard (watch-mode testing via Guardfile). Rake tasks available in lib/tasks/tasks.rake. No server to start—this is middleware injected into your Rails/Sinatra app.

• lib/secure_headers.rb — Main entry point and public API facade that coordinates all security header configuration and application
• lib/secure_headers/configuration.rb — Central configuration management that holds all security header defaults, overrides, and per-action settings
• lib/secure_headers/headers/content_security_policy.rb — CSP implementation handling the most complex security header with directive merging and validation logic
• lib/secure_headers/middleware.rb — Request/response middleware that applies configured headers to all HTTP responses in the Rails stack
• lib/secure_headers/railtie.rb — Rails integration point that hooks the gem into the Rails initialization and request lifecycle
• lib/secure_headers/headers/policy_management.rb — Shared policy base class and directive merging logic used across all policy-based headers (CSP, CSP report-only)
• lib/secure_headers/hash_helper.rb — Utility for deep merging and manipulating configuration hashes across all header configurations

• SecureHeaders module (lib/secure_headers.rb) (Ruby modules, class methods) — Public API: configure(), apply_headers(), override_x(), use_original_headers(). Routes calls to appropriate header classes.
  • Failure mode: Invalid configuration passed to apply_headers causes header generation to fail; apply_headers should raise ArgumentError
• Configuration class (Hash merging, thread-local storage (RequestStore or Thread.current)) — Stores global and per-action header configs, merges defaults with overrides, manages thread-local per-action state
  • Failure mode: Thread-local state leaks across requests in concurrent environments; per-action config not properly cleaned up

Add a new security header

1. Create a new header class in lib/secure_headers/headers/ inheriting from appropriate base (PolicyManagement for directive-based headers or standalone) (lib/secure_headers/headers/new_header.rb)
2. Add configuration defaults in the HEADERS constant within lib/secure_headers/configuration.rb (lib/secure_headers/configuration.rb)
3. Implement #value method returning the header string value and handle any directive merging logic (lib/secure_headers/headers/new_header.rb)
4. Register the header in lib/secure_headers.rb by adding it to the headers hash returned from apply_headers (lib/secure_headers.rb)
5. Create comprehensive tests in spec/lib/secure_headers/headers/new_header_spec.rb covering defaults, overrides, and edge cases (spec/lib/secure_headers/headers/new_header_spec.rb)

Override security headers for a specific action

1. In a Rails controller, call SecureHeaders.override_x to set per-action config using the named override pattern (lib/secure_headers.rb)
2. Call SecureHeaders.use_original_headers(only: [:action]) to restore defaults for specific actions (lib/secure_headers.rb)
3. Optionally use view helpers in templates to append directives inline via SecureHeaders.append_content_security_policy_directives (lib/secure_headers/view_helper.rb)

Configure and validate CSP for production

1. Define CSP configuration in config/secure_headers.yml or via SecureHeaders.configure with directives mapping (lib/secure_headers/configuration.rb)
2. Use report-uri directive to configure CSP violation reporting endpoint (lib/secure_headers/headers/content_security_policy.rb)
3. Enable CSP report-only mode during validation period by setting enforcement: false in CSP config (lib/secure_headers/headers/content_security_policy.rb)
4. Parse and analyze CSP violation reports using SecureHeaders.process_csp_violations Rake task (lib/secure_headers/task_helper.rb)

• Rack Middleware — Framework-agnostic way to inject headers into all HTTP responses before they reach the browser
• Rails Railtie — Hooks into Rails initialization lifecycle to auto-register middleware and integrate with Rails conventions
• Configuration DSL with Hash Merging — Allows safe per-action overrides and appends without mutating global state; supports named override patterns
• Policy base class with directive merging — CSP and related headers require complex directive merging logic; shared base eliminates duplication

• Configuration stored in Ruby hashes rather than dedicated objects

  • Why: Simpler API, leverages existing Hash merging patterns, easier for users to override
  • Consequence: Less type safety; requires validation at apply time rather than compile time

• Per-action overrides via class variables and thread-local storage

  • Why: Allows dynamic per-request configuration without changing method signatures
  • Consequence: Risk of thread leakage in concurrent environments; requires careful cleanup

• Nonce generation deferred to header-building time

  • Why: Avoids nonce pre-generation for requests that might not render CSP headers
  • Consequence: Nonces unavailable in views until response building phase; requires view helper for access

• Single source of truth in Configuration class with no caching

  • Why: Ensures per-action overrides are always respected without cache invalidation complexity
  • Consequence: Configuration lookup happens on every request; potential minor performance impact at scale

• Does not enforce HTTP/HTTPS enforcement (delegated to HSTS header and deployment configuration)
• Does not provide real-time CSP violation alerting (only collection and parsing via Rake tasks)
• Does not auto-generate CSP directives from code analysis (CSP must be explicitly configured)
• Does not support non-Rails frameworks at the middleware level (Sinatra requires manual integration)

1. The gem requires explicit SecureHeaders.configure { |config| } call or it will raise exceptions—no true 'defaults-only' mode exists despite README mentioning it. 2) Cookie configuration in lib/secure_headers/utils/cookies_config.rb modifies all cookies globally via middleware; filtering by cookie name requires custom middleware wrapping. 3) CSP nonce generation (in content_security_policy.rb) requires view helper SecureHeaders.content_security_policy_nonce from lib/secure_headers/view_helper.rb—nonce must be manually injected in templates or it won't work. 4) The gem patches HTTP response headers directly; incompatible with response streaming middleware that has already begun sending headers.

• Content Security Policy (CSP) with nonce-based injection — CSP is the primary defense against XSS in modern applications; this gem's nonce generation (view_helper.rb + content_security_policy.rb) allows inline scripts/styles safely without whitelist sprawl
• HTTP Strict Transport Security (HSTS) — HSTS forces browsers to always use HTTPS, preventing SSLStrip attacks; understanding max-age and preload semantics is critical for production deployment
• Rack middleware pattern — secure_headers uses Rack middleware (middleware.rb) to inject headers into every response in a framework-agnostic way; understanding this pattern is essential for modifying behavior
• Per-request configuration override with global defaults — The gem allows global SecureHeaders.configure() plus per-action overrides; this pattern (in configuration.rb) is key to understanding how to customize security posture per endpoint
• SameSite cookie attribute (Strict/Lax/None) — Modern CSRF defense via cookies; this gem auto-sets SameSite=Lax on all cookies (cookies_config.rb), but understanding when to use Strict vs None is critical for cross-site requests
• Cryptographic hashing for CSP script/style allowlisting — hash_helper.rb computes SHA256/384/512 hashes of inline assets for CSP allowlisting; this allows safe inline code without opening XSS vectors
• X-Frame-Options and clickjacking prevention — DENY vs SAMEORIGIN choice prevents UI redressing attacks; understanding the trade-off is essential for APIs vs traditional web apps

• rails/rails — The primary target framework that secure_headers integrates with via railtie.rb and middleware
• sinatra/sinatra — Secondary target framework with docs/sinatra.md and middleware support for the Rack protocol
• rack/rack — Foundation protocol that secure_headers middleware implements to work across Rails/Sinatra/any Rack app
• rubocop/rubocop — Ruby linting tool configured in .rubocop.yml for consistent code style across the gem
• rspec/rspec — Testing framework used extensively in the spec/ directory (.rspec config file present)

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for Sinatra middleware in spec/lib/secure_headers/middleware_spec.rb

The repo has a docs/sinatra.md file indicating Sinatra support, but the middleware_spec.rb only tests Rails integration. There are no dedicated Sinatra integration tests. Adding comprehensive Sinatra middleware tests would validate the documented Sinatra functionality and catch regressions in non-Rails frameworks.

• [ ] Create Sinatra test helper setup in spec/lib/secure_headers/middleware_spec.rb or new dedicated spec file
• [ ] Test middleware applies headers correctly in Sinatra request/response cycle
• [ ] Test per-action configuration works with Sinatra route-level hooks
• [ ] Verify cookie handling works in Sinatra context (reference lib/secure_headers/utils/cookies_config.rb)
• [ ] Test error handling and edge cases specific to Sinatra

Add CI workflow for dependency vulnerability scanning and Ruby version matrix testing

The .github/workflows/build.yml exists but the repo lacks explicit testing across multiple Ruby versions and automated vulnerability scanning. The .ruby-version file and gemspec indicate multi-version support should be tested. Adding a matrix-based workflow and Dependabot integration would catch compatibility issues early.

• [ ] Extend .github/workflows/build.yml to include Ruby version matrix (2.7+, 3.0+, 3.1, 3.2, 3.3)
• [ ] Add workflow step to run 'bundle audit' or similar dependency vulnerability check
• [ ] Verify tests pass across all Ruby versions in the matrix
• [ ] Test against multiple Rails versions (5.2, 6.0, 6.1, 7.0, 7.1) if applicable
• [ ] Document Ruby/Rails version support requirements in README.md

Add missing tests for lib/secure_headers/utils/cookies_config.rb

The cookies_config.rb utility module exists but there is no corresponding spec/lib/secure_headers/utils/cookies_config_spec.rb file in the test structure. Cookie configuration is critical security functionality referenced in docs/cookies.md. Full unit test coverage would prevent regressions in cookie handling.

• [ ] Create spec/lib/secure_headers/utils/cookies_config_spec.rb
• [ ] Add tests for cookie parsing and validation logic
• [ ] Test edge cases: malformed cookies, special characters, encoding/decoding
• [ ] Test integration with lib/secure_headers/headers/cookie.rb header generation
• [ ] Test configuration merging and override behavior documented in docs/cookies.md
• [ ] Verify Secure, HttpOnly, SameSite attribute handling across scenarios

• Add missing documentation for expect-ct and clear-site-data headers in docs/ folder—both are implemented in lib/secure_headers/headers/ but lack dedicated usage guides like CSP has
• Add comprehensive integration test for Sinatra support in spec/—currently only documented in docs/sinatra.md but test coverage is sparse compared to Rails
• Create example Rails/Sinatra application in examples/ folder showing complete setup with CSP nonce generation, cookie security, and per-action overrides—would validate documentation accuracy

The secure_headers gem demonstrates a strong security-focused design with dedicated modules for managing various security headers (CSP, HSTS, X-Frame-Options, etc.). The codebase structure shows good separation of concerns and comprehensive test coverage. No critical vulnerabilities were identified in the file structure or configuration. However, a complete assessment requires: (1) Full dependency analysis (Gemfile contents not provided), (2) Review of actual implementation code in lib/ directory for injection risks or unsafe patterns, and (3) Verification that header generation properly sanitizes all user-controlled input. The project follows Ruby/Rails security best practices with a dedicated security header management gem. Consider running 'bundle audit' and SAST tools on the complete codebase for comprehensive vulnerability assessment.

• Low · Missing Dependency Lock File Details — Gemfile / Gemfile.lock. The provided dependency information is empty. Unable to verify if any gems have known security vulnerabilities. The Gemfile exists but its contents were not provided for analysis. Fix: Provide Gemfile and Gemfile.lock contents for dependency vulnerability scanning. Run 'bundle audit' regularly to check for vulnerable gem versions.
• Low · Potential Information Disclosure via Documentation — docs/upgrading-to-*.md files. Multiple upgrade documentation files (upgrading-to-*.md) are present, which could help attackers understand version-specific vulnerabilities. While documentation is important, detailed migration guides may reveal security-relevant implementation details. Fix: Review documentation for sensitive implementation details that could aid attackers. Consider separating public documentation from internal implementation details when discussing security changes.

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.