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/StackExchange/blackbox 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 all four use cases

• Last commit 6mo ago
• 41+ active contributors
• Distributed ownership (top contributor 28% of recent commits)
• MIT licensed
• CI configured
• Tests present
• ⚠ Slowing — last commit 6mo ago

_{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 StackExchange/blackbox repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/StackExchange/blackbox.

What it runs against: a local clone of StackExchange/blackbox — 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 StackExchange/blackbox | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 213 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of StackExchange/blackbox. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/StackExchange/blackbox.git
#   cd blackbox
#
# 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 StackExchange/blackbox and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "StackExchange/blackbox(\\.git)?\\b" \\
  && ok "origin remote is StackExchange/blackbox" \\
  || miss "origin remote is not StackExchange/blackbox (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "cmd/blackbox/blackbox.go" \\
  && ok "cmd/blackbox/blackbox.go" \\
  || miss "missing critical file: cmd/blackbox/blackbox.go"
test -f "cmd/blackbox/cli.go" \\
  && ok "cmd/blackbox/cli.go" \\
  || miss "missing critical file: cmd/blackbox/cli.go"
test -f "cmd/blackbox/drive.go" \\
  && ok "cmd/blackbox/drive.go" \\
  || miss "missing critical file: cmd/blackbox/drive.go"
test -f "models/crypters.go" \\
  && ok "models/crypters.go" \\
  || miss "missing critical file: models/crypters.go"
test -f "models/vcs.go" \\
  && ok "models/vcs.go" \\
  || miss "missing critical file: models/vcs.go"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 213 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~183d)"
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/StackExchange/blackbox"
  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).

BlackBox is a GPG-based secret encryption wrapper that encrypts individual files at rest in Git/Mercurial/Subversion repositories. It wraps GNU Privacy Guard with simple commands (like blackbox_edit, blackbox_decrypt_all_files) to manage encrypted secrets without requiring developers to understand complex GPG flags. Dual-architecture project: original shell scripts in bin/ (including _blackbox_common.sh as shared utilities) and Go v2 implementation in binv2/ wrapping the same command set. Build orchestration via Makefile and bin/Makefile. CLI v1 uses shell scripting; v2 uses Go with urfave/cli framework. Configuration stored in .blackbox/ directory (inferred from design docs).

DevOps engineers, system administrators, and infrastructure-as-code teams (originally Puppet users, now general VCS users) who need to safely store API keys, credentials, and configuration secrets alongside code in version control while maintaining audit trails.

ABANDONED — the project explicitly states 'THIS PROJECT IS ABANDONED. DO NOT USE. DO NOT SUBMIT BUG REPORTS OR PRs' in the README. While it has CircleCI and GitHub Actions CI configured, there are no recent commits visible and the recommendation is to use alternative solutions like git-crypt, Conjur, AWS KMS, or Azure Key Vault.

HIGH RISK: Project is abandoned with no active maintenance. Go module dependencies are from 2020 (urfave/cli v2.2.0). Switching to this for new projects is explicitly discouraged by maintainers. The codebase has dual implementations (shell scripts in bin/ and Go in binv2/) with unclear migration status.

No active development — project is in archived/abandoned state. The last activity appears to be documentation and CI setup. Version 2 rewrite in Go exists in binv2/ but migration/completion status is unclear. Version2-Ideas.md and README-v2.md suggest incomplete v2 transition.

Clone and explore (build not recommended for production): git clone https://github.com/StackExchange/blackbox.git && cd blackbox && make (see Makefile for build targets). However, the README explicitly warns against using this project — consider alternatives like git-crypt or dedicated secret management services instead.

Daily commands: Not recommended for new projects. Legacy: bin/blackbox_initialize initializes a repo. Development: make in root builds v2 binaries. Testing: bin/_blackbox_common_test.sh runs shell script tests. See Makefile and bin/Makefile for targets.

• cmd/blackbox/blackbox.go — Main entry point for the Go v2 implementation; all CLI invocations flow through here.
• cmd/blackbox/cli.go — CLI command definitions and routing using urfave/cli; defines the interface users interact with.
• cmd/blackbox/drive.go — Core orchestration logic for encryption/decryption workflows; drives all secret management operations.
• models/crypters.go — Abstraction layer for GPG encryption backends; critical for understanding how secrets are actually protected.
• models/vcs.go — Version control system abstraction; handles Git, Mercurial, and Subversion integration.
• bin/_blackbox_common.sh — Shared bash utilities for all v1 shell scripts; contains common functions used across all operations.
• DESIGN.md — Architecture and design rationale; essential for understanding the philosophy and constraints.

Add a new blackbox command

1. Define the command handler function in cmd/blackbox/cli.go following the pattern of existing commands (e.g., cmdDecrypt, cmdEdit) (cmd/blackbox/cli.go)
2. Add the command to the app.Commands slice with name, usage, flags, and action function (cmd/blackbox/cli.go)
3. Implement orchestration logic in cmd/blackbox/drive.go if the command involves encryption/decryption or VCS operations (cmd/blackbox/drive.go)
4. Add integration tests validating the command with real GPG keys and VCS operations (integrationTest/integration_test.go)

Support a new VCS backend

1. Add a new VCS type constant and implementation struct (e.g., type PerforceVCS struct) in models/vcs.go (models/vcs.go)
2. Implement required methods: FileStatus(), CommitChanges(), ListFiles(), GetAdminList(), UpdateAdminList() (models/vcs.go)
3. Update VCS detection logic in drive.go's DetermineVCS() function to recognize the new system (cmd/blackbox/drive.go)
4. Add integration tests verifying initialization, encryption, and admin operations with the new VCS (integrationTest/integration_test.go)

Extend GPG key management or encryption strategy

1. Review and extend the Crypter interface in models/crypters.go to add new methods or parameters (models/crypters.go)
2. Implement the new behavior in the GPGCrypter type, wrapping gpg command-line invocations (models/crypters.go)
3. Update drive.go to call the new crypter methods during initialization or encryption workflows (cmd/blackbox/drive.go)
4. Add tests validating the new encryption behavior with multiple admin keys and file operations (integrationTest/integration_test.go)

• GPG (GnuPG) — Industry-standard for encrypted key management; provides secure key storage, multi-recipient encryption, and trust model aligned with team-based secret sharing.
• Go 1.14+ — Cross-platform compiled binary; enables single distributable tool supporting multiple VCS backends without runtime dependencies.
• urfave/cli v2 — Simplifies CLI parsing and command routing; provides consistent help, flags, and subcommand structure for user-facing operations.
• Bash shell scripts (v1 legacy) — Minimal dependencies for backward compatibility and initialization bootstrap; allows users without Go toolchain to use legacy commands.
• VCS integration (Git/Hg/Svn) — Encrypts secrets at-rest in the repository while leveraging native VCS workflows; secrets tracked in .blackbox metadata files without exposing plaintext.

• GPG-based encryption vs. custom cryptography

  • Why: GPG is well-audited, battle-tested, and familiar to security practitioners; avoids introducing cryptographic vulnerabilities.
  • Consequence: Requires users to have GPG installed and understand key management; higher operational overhead than simpler secrets engines like Vault.

• Dual implementation (v1 bash + v2 Go)

  • Why: v1 provides backward compatibility and minimal bootstrap overhead; v2 adds stronger typing, testability, and cross-platform support.
  • Consequence: Code duplication and maintenance burden; users must understand which version to use (project is abandoned—v1 legacy code still present).

• File-level encryption rather than field-level

  • Why: Simpler to implement, audit, and integrate with version control; entire file encrypted as atomic unit.
  • Consequence: Cannot selectively decrypt parts of a file; editing requires decrypting entire file (intended for configuration files, not huge datasets).

• Admin list stored in .blackbox/blackbox-admins.txt in plaintext

  • Why: Allows VCS to track which keys can decrypt without storing keys in repo; admin list is not sensitive.
  • Consequence: Requires bootstrapping: initial repo setup must use out-of-band key exchange or manual admin key distribution.

• Real-time key rotation or expiration enforcement—relies on manual admin updates via blackbox_removeadmin and blackbox_update_all_files.
• Field-level or row-level encryption—operates only at file granularity.
• Key escrow or recovery—no master key or backup mechanism; loss of all admin keys means encrypted files are unrecoverable.
• Handling of symmetric secrets or non-GPG encryption methods—GPG is the only supported cryptographic backend.
• Support for non-human accounts with long-lived credentials—role accounts require manual setup and GPG key management.
• Continuous integration with CI/CD without human intervention—deployment requires admin to decrypt files at runtime.

Critical: Project is abandoned — do not use for new deployments. Dual implementations: shell v1 (bin/) vs Go v2 (binv2/) — unclear which is canonical or complete; tests may not cover v2. GPG dependency: requires local GPG key setup and trust model (see DESIGN.md for key registration), no built-in key distribution. VCS assumptions: expects .blackbox/ admin list and enrolled files list in repo root (magic directory pattern). Older Go version: requires Go 1.14+; module dependencies frozen at 2020. No secret rotation: designed for static secrets (API keys), not rotating credentials.

• GPG Key Signing & Trust Model — BlackBox requires each team member to have a GPG key pair and admin keys must sign/trust each other — understanding GPG trust webs is essential to troubleshoot key enrollment issues in blackbox_addadmin
• Symmetric vs Asymmetric Encryption — BlackBox uses GPG's asymmetric encryption (public key cryptography) to encrypt files to multiple recipients simultaneously — different from AES symmetric encryption used by alternatives like git-crypt
• File Envelope Pattern (Multi-Recipient Encryption) — BlackBox encrypts each file to all admin GPG keys in .blackbox/admins simultaneously, creating a single encrypted artifact readable by any admin — critical to understand why rekeying requires blackbox_update_all_files
• Shell Script Arg Processing & Function Libraries — BlackBox v1 is entirely shell-based with heavy use of sourced libraries (_blackbox_common.sh), subshells, and gpg piping — understanding shell positional args and error propagation is essential to debug or extend bin/ scripts
• VCS-Agnostic Wrapper Pattern — BlackBox detects VCS type (Git/Mercurial/SVN) at runtime using tree-walking and tool presence checks — understanding how _blackbox_common.sh abstracts VCS differences explains why commands work across multiple version control systems
• Diff-Based Secrets Review (blackbox_diff) — BlackBox allows decrypting only the delta between commits for audit trails via blackbox_diff — requires understanding how GPG can be streamed and diffed without exposing full plaintext to Git history
• Configuration Management Integration Patterns — BlackBox is designed as a pre-deployment decryption step for Puppet/Ansible — understanding blackbox_postdeploy and file enrollment workflows shows how to integrate encrypted secrets into CI/CD pipelines

• AGWA/git-crypt — Direct successor recommended in BlackBox README — uses transparent encryption at the Git level rather than wrapping GPG manually
• mozilla/sops — Modern alternative for storing encrypted secrets in VCS with YAML/JSON support and cloud KMS backend integration
• CyberArk/conjur — Enterprise secret management system that BlackBox README recommends as the preferred approach (store Conjur API keys via BlackBox)
• aws/aws-kms-encryption-terraform — AWS KMS alternative mentioned in README for production secret rotation and envelope encryption patterns
• StackExchange/dnscontrol — Sibling StackExchange project that uses similar VCS + secrets pattern for configuration management

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 comprehensive test suite for binv2 Go implementation

The repo has both legacy shell scripts (bin/) and a newer Go v2 implementation (binv2/ and cmd/blackbox/). While there's a test file for shell scripts (_blackbox_common_test.sh), there are no visible Go tests for the cmd/blackbox package. The Go implementation is the future direction but lacks unit test coverage, making it risky for contributors to modify core encryption/decryption logic. Adding tests would improve code quality and enable safer refactoring.

• [ ] Create cmd/blackbox/*_test.go files covering cli.go (argument parsing), drive.go (core operations), and blackbox.go (main logic)
• [ ] Add test fixtures in a testdata/ directory with sample encrypted/unencrypted files
• [ ] Test core operations: decrypt_file, encrypt_file, edit workflows, and admin management
• [ ] Update .github/workflows/build.yml to run 'go test ./...' in CI pipeline
• [ ] Document test execution in RELEASE_ENGINEERING.md

Create migration guide from binv2 (shell) to v2 (Go) implementation

The repo has two parallel implementations: legacy shell scripts in bin/, shell v2 in binv2/, and new Go v2 in cmd/blackbox/. README-v2.md and Version2-Ideas.md exist but there's no clear migration guide. New contributors are confused about which version to use/maintain. A comprehensive migration document would clarify the v2 transition path and document which features are implemented in Go vs still in shell.

• [ ] Create docs/migration-guide-v1-to-v2.md explaining the shell→Go transition timeline
• [ ] Add feature parity matrix table showing which commands exist in bin/, binv2/, and cmd/blackbox/
• [ ] Document known gaps between shell and Go implementations (reference DESIGN.md for context)
• [ ] Add troubleshooting section for common issues during migration
• [ ] Update README.md with clear recommendation on which version to use for new projects

Add GitHub Actions workflow for automated GPG/cryptography testing

The project is a GPG-based encryption tool but .github/workflows/build.yml and release.yml likely don't test the actual encryption/decryption workflows with real GPG keys. This is critical for security. Adding a dedicated GPG test workflow would ensure encryption operations work correctly across different GPG versions and catch regressions in core functionality.

• [ ] Create .github/workflows/crypto-tests.yml that sets up GPG with test keys
• [ ] Generate test GPG keypairs in the workflow (reference bin/_blackbox_common_test.sh for existing test patterns)
• [ ] Add integration tests for: initialize repo, add admin, register file, encrypt, decrypt, edit workflows
• [ ] Test against multiple GPG versions (3.0, 2.3, 2.2) using matrix strategy
• [ ] Add test for the actual bin/Makefile targets that integration tests depend on

• Add comprehensive v2 migration tests: binv2/ Go implementations exist but bin/_blackbox_common_test.sh only tests shell scripts. Create test parity by writing Go tests (e.g. for blackbox_edit, blackbox_decrypt_all_files) to validate v2 behavior matches v1.
• Document .blackbox/ schema: DESIGN.md explains why the system works but not the exact format/structure of .blackbox/admins, .blackbox/files, or key file naming. Add a schema reference document with examples.
• Fix CI for v2: .github/workflows/build.yml and .circleci/config.yml exist but it's unclear if they test binv2/. Verify CI actually runs Go tests and audit logging if v2 binaries are being validated.

• High · Abandoned Project - No Security Maintenance — README.md. The README explicitly states 'THIS PROJECT IS ABANDONED. DO NOT USE. DO NOT SUBMIT BUG REPORTS OR PRs.' This means no security patches, vulnerability fixes, or updates will be provided. Any vulnerabilities discovered will remain unpatched. Fix: Do not use this project in production. Migrate to actively maintained alternatives listed in the documentation (e.g., HashiCorp Vault, AWS Secrets Manager, SOPS, git-crypt).
• High · Outdated Go Version — go.mod. The project specifies 'go 1.14' in go.mod, which was released in February 2020 and is far beyond its support lifecycle. This version contains numerous known security vulnerabilities and receives no updates. Fix: Upgrade to the latest stable Go version (1.21+). Update all dependencies to their latest versions and test thoroughly.
• High · Outdated Dependencies with Known Vulnerabilities — go.mod, go.sum. Multiple dependencies have pinned versions from 2019-2020 and likely contain known security vulnerabilities: urfave/cli/v2 v2.2.0 (released 2020), olekukonko/tablewriter (no version specified), and others. These packages have had numerous security updates since. Fix: Update all dependencies to their latest versions: run 'go get -u ./...' and 'go mod tidy'. Audit dependencies using 'go list -u -m all' and tools like 'nancy' or 'govulncheck'.
• Medium · Shell Script Code Injection Risk — bin/*.sh, binv2/* scripts. The codebase contains numerous shell scripts (bin/ and binv2/ directories) that interact with GPG and file systems. Shell scripts are inherently vulnerable to injection attacks if user input is not properly sanitized. Files like blackbox_cat, blackbox_edit, blackbox_decrypt_file could be at risk. Fix: Conduct a thorough security audit of all shell scripts, particularly focusing on: (1) Proper quoting of variables, (2) Input validation and sanitization, (3) Use of 'set -e' and 'set -u' flags, (4) Avoiding eval and other dynamic code execution, (5) Consider rewriting in a type-safe language.
• Medium · GPG Security Practices Not Documented — docs/encryption.md, docs/gnupg-tips.md. While the project handles GPG encryption, security best practices for key management, key rotation, trust model, and secure key storage are not clearly documented in the visible files. This could lead to improper implementation by users. Fix: Create comprehensive security guidelines covering: (1) Key rotation policies, (2) Key revocation procedures, (3) Trust model recommendations, (4) Secure key storage on developer machines, (5) Key expiration policies.
• Medium · No Input Validation in Go CLI — cmd/blackbox/cli.go, cmd/blackbox/drive.go. The Go CLI implementation (cmd/blackbox/cli.go, cmd/blackbox/drive.go) may not properly validate all user inputs before passing them to GPG or file operations, potentially leading to command injection or path traversal vulnerabilities. Fix: Implement strict input validation for all CLI arguments, especially filenames and paths. Use a whitelist approach and reject any suspicious patterns. Validate all external command invocations.
• Low · Missing Security Headers and Configuration — .circleci/config.yml, .github/workflows/build.yml. No evidence of security configurations in the CI/CD pipeline (.circleci/config.yml, .github/workflows/) such as security scanning, dependency auditing, or SAST tools. Fix: Integrate security tools into CI/CD: (1) Dependency vulnerability scanning (Snyk, Dependabot), (2) SAST scanning (GoVulnCheck, gosec), (3) SBOM generation, (4) Code signing for releases.
• Low · Incomplete Security Documentation — README.md. The README is cut off and doesn't complete its warning statement. Critical security documentation may be incomplete or missing. Fix: Complete all documentation

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.