git-hardening/.design/git-harden.md

Feature: git-harden.sh

Summary

A single-file bash script that audits and hardens a developer's global git configuration with security-focused defaults. It runs an audit-first flow (color-coded report of current state), then interactively applies recommended settings covering object integrity, protocol restrictions, filesystem protection, hook control, SSH signing with FIDO2 support, SSH transport hardening, and credential security. A -y flag auto-applies all defaults, and --audit exits after the report for CI use.

Requirements

• REQ-1: The script must audit all git global config settings listed in the Architecture section and report each as [OK] (matches recommended), [WARN] (set to non-recommended value), or [MISS] (not configured), with color-coded output to stderr.
• REQ-2: The script must apply hardening settings via git config --global in interactive mode (prompt per setting, default Y) or auto-apply mode (-y).
• REQ-3: The script must back up the current global git config to ~/.config/git/pre-harden-backup-<timestamp>.txt before making any changes.
• REQ-4: The script must detect the platform (macOS/Linux) and select the appropriate credential helper (osxkeychain on macOS, libsecret or cache on Linux).
• REQ-5: The script must provide an SSH signing setup wizard with two tiers: software SSH key (ed25519) and FIDO2 hardware key (ed25519-sk), detecting existing keys and hardware automatically.
• REQ-6: In -y mode, signing must only be enabled (commit.gpgsign, tag.gpgsign) if a valid signing key is detected and its public key file is readable. If no key exists, only non-breaking settings (gpg.format, gpg.ssh.allowedSignersFile) are configured.
• REQ-7: The script must audit and optionally harden ~/.ssh/config with secure defaults (StrictHostKeyChecking accept-new, HashKnownHosts yes, IdentitiesOnly yes, AddKeysToAgent yes, modern PubkeyAcceptedAlgorithms).
• REQ-8: The script must print admin/org-level recommendations (branch protection, vigilant mode, force-push policy, token hygiene) as informational output without applying changes.
• REQ-9: The script must be compatible with Bash 3.2 (macOS default). No associative arrays, no mapfile/readarray, no ${var,,} case conversion, no declare -A.
• REQ-10: The script must be idempotent — re-running it on an already-hardened system changes nothing.
• REQ-11: Exit codes must be: 0 (all OK or changes applied), 1 (error), 2 (audit found issues).
• REQ-12: The script must pass shellcheck with no errors or warnings.

Acceptance Criteria

• AC-1: Running git-harden.sh --audit on a fresh git config prints a report with [MISS] for all 20+ hardening settings and exits with code 2.
• AC-2: Running git-harden.sh -y on a fresh config applies all settings; a subsequent --audit exits with code 0 (all [OK]).
• AC-3: Running git-harden.sh -y twice produces identical git config output (idempotent).
• AC-4: On macOS, credential.helper is set to osxkeychain. On Linux with libsecret available, it uses the detected libsecret path; otherwise cache --timeout=3600.
• AC-5: If credential.helper is currently store, the audit reports [WARN] and interactive mode offers to replace it.
• AC-6: The signing wizard detects existing ~/.ssh/id_ed25519 and offers to use it as signing key.
• AC-7: If a FIDO2 device is detected (via ykman info or fido2-token -L), the wizard offers Tier 2 (generate ed25519-sk key). The ssh-keygen stderr is not suppressed.
• AC-8: In -y mode with no SSH key present, commit.gpgsign and tag.gpgsign are NOT set. A note is printed directing the user to run interactively.
• AC-9: ~/.config/git/hooks/ directory is created if missing. core.hooksPath is set with literal ~ (not expanded).
• AC-10: ~/.ssh/config is created with mode 600 (and ~/.ssh/ with mode 700) if they don't exist. SSH directives are only appended if not already present.
• AC-11: The script runs without error on Bash 3.2.57 (macOS default) and Bash 5.x (Linux).
• AC-12: shellcheck git-harden.sh produces zero errors and zero warnings.
• AC-13: A config backup file is created at ~/.config/git/pre-harden-backup-<timestamp>.txt before any changes are made.
• AC-14: protocol.allow is set to never; only https, ssh, and file (as user) are whitelisted. git:// and ext:// are explicitly blocked.
• AC-15: If pull.rebase is currently set, the audit phase reports a [WARN] about the conflict with pull.ff=only.

Architecture

The script is a single file git-harden.sh at the repo root, using #!/usr/bin/env bash with strict mode (set -o errexit, set -o nounset, set -o pipefail, IFS=$'\n\t').

Internal structure (functions)

All variables inside functions use local. Global constants use readonly UPPER_CASE. The script follows the conventions in AGENTS.md (Shell Script Development Standards v2.0).

Entry point and argument parsing:

• main() — orchestrates the full flow: preflight, audit, apply, recommendations
• parse_args() — handles -y, --audit, --help flags
• die() — fatal error handler (prints to stderr, exits 1)

Platform detection:

• detect_platform() — sets PLATFORM to macos or linux via uname -s
• check_dependencies() — verifies git >= 2.34.0, ssh-keygen present; detects optional tools (ykman, fido2-token, credential helpers)

Audit functions (read-only, no side effects):

• audit_git_config() — checks each hardening setting against git config --global --get
• audit_ssh_config() — checks ~/.ssh/config for recommended directives
• audit_signing() — checks signing config and key availability
• print_audit_report() — renders the color-coded report to stderr

Apply functions (write operations):

• apply_git_config() — sets each non-OK setting via git config --global
• apply_ssh_config() — appends missing directives to ~/.ssh/config
• signing_wizard() — interactive signing setup (tier selection, key generation/detection)
• detect_existing_keys() — scans ~/.ssh/ and ~/.ssh/config IdentityFile directives
• detect_fido2_hardware() — checks ykman info and fido2-token -L
• generate_ssh_key() — wraps ssh-keygen -t ed25519
• generate_fido2_key() — wraps ssh-keygen -t ed25519-sk with touch prompt
• setup_allowed_signers() — creates/updates ~/.config/git/allowed_signers
• print_admin_recommendations() — prints org-level advice to stderr

Helpers:

• prompt_yn() — prompt with configurable default, respects -y mode
• print_ok(), print_warn(), print_miss() — color-coded status output to stderr

Git config settings applied

Object integrity: transfer.fsckObjects=true, fetch.fsckObjects=true, receive.fsckObjects=true

Protocol restrictions (default deny): protocol.allow=never, protocol.https.allow=always, protocol.ssh.allow=always, protocol.file.allow=user, protocol.git.allow=never, protocol.ext.allow=never

Filesystem protection: core.protectNTFS=true, core.protectHFS=true, core.fsmonitor=false

Hook control: core.hooksPath=~/.config/git/hooks

Repository safety: safe.bareRepository=explicit, submodule.recurse=false

Pull/merge hardening: pull.ff=only, merge.ff=only

Transport security: url."https://".insteadOf=http://, http.sslVerify=true

Credential storage: credential.helper (platform-detected)

Signing: gpg.format=ssh, user.signingkey (detected), commit.gpgsign=true, tag.gpgsign=true, tag.forceSignAnnotated=true, gpg.ssh.allowedSignersFile=~/.config/git/allowed_signers

Visibility: log.showSignature=true

Optional (interactive only): core.symlinks=false, merge.verifySignatures=true

SSH config directives appended to ~/.ssh/config

StrictHostKeyChecking accept-new, HashKnownHosts yes, IdentitiesOnly yes, AddKeysToAgent yes, PubkeyAcceptedAlgorithms ssh-ed25519,sk-ssh-ed25519@openssh.com,ecdsa-sha2-nistp256,sk-ecdsa-sha2-nistp256@openssh.com

Dependencies

Required: git >= 2.34.0, ssh-keygen Optional: ykman or fido2-token (FIDO2 detection), OS keychain (osxkeychain on macOS, libsecret on Linux)

Open Questions

No unresolved questions remain. All design decisions have been validated through brainstorming, research, spec review, and external review.

Out of Scope

• GPG signing support — SSH signing covers the same use cases with far less complexity
• Server-side changes — the script only modifies the developer's local config
• Undo/restore command — the script is idempotent; devs can manually unset any setting with git config --global --unset
• Windows/WSL support
• Per-repo config modification — global config only
• jj support
• Hook dispatcher scripts for projects using husky/lefthook/pre-commit — mentioned in admin recommendations but not implemented