# Secret Management and Credential Safety **Audience:** All developers contributing to [hmislk/hmis](https://github.com/hmislk/hmis) > **Why this matters:** hmislk/hmis is an open-source repository. Any credential, password, or customer-identifying information committed to git is **permanently public**, even after deletion from the latest branch. Git history is immutable and anyone can have already cloned it. --- ## What Must Never Be Committed | Category | Examples | |---|---| | Database passwords | MySQL passwords, JNDI datasource passwords | | Application server credentials | Payara admin password, `master-password` file | | API keys | Anthropic API key, Cloudflare API token | | Customer infrastructure | Production IP addresses, server hostnames | | TLS/SSL material | `.pem`, `.jks`, `.p12`, `.key`, `.cer` files | | Environment files | `.env`, `secrets.properties`, `credentials.xml` | | Payara domain config | `domain.xml`, `glassfish-resources.xml` (already in `.gitignore`) | --- ## How the Project Is Protected ### 1. `.gitignore` blocks known sensitive files The project `.gitignore` (root of repo) blocks: ``` domain.xml glassfish-resources.xml *.jks *.p12 *.pem *.key .env secrets.properties *-credentials.properties ``` These files are never tracked. If you need to share config, use a password manager or a private channel — never a GitHub comment or commit. ### 2. `persistence.xml` uses JNDI — not hardcoded credentials Our `src/main/resources/META-INF/persistence.xml` only references JNDI names: ```xml jdbc/coop ``` The actual database URL, username, and password are defined **only in the Payara admin console** (`domain.xml`), which is never committed. This is the correct pattern — never change it to hardcode credentials. ### 3. Pre-commit hook with gitleaks Every developer should install the project's git security hooks. These run [gitleaks](https://github.com/gitleaks/gitleaks) on every `git commit` attempt and **block the commit** if secrets are detected. --- ## Developer Setup (Required) Run this once after cloning the repo: ```bash chmod +x scripts/install-dev-hooks.sh ./scripts/install-dev-hooks.sh ``` This script: 1. Installs `gitleaks` to `~/bin/` if not present 2. Installs `pre-commit` via pip if not present 3. Installs the pre-commit hook into `.git/hooks/pre-commit` After this, every `git commit` will be automatically scanned. ### Manual test ```bash gitleaks detect --config=.gitleaks.toml -v ``` --- ## Config Files That Are Safe to Commit | File | Why It's Safe | |---|---| | `persistence.xml` | Contains only JNDI name, no credentials | | `web.xml` | No credentials | | `beans.xml` | CDI config, no credentials | | Migration SQL files | Schema changes only, no data | | `pom.xml` | Build config, no credentials | --- ## The Correct Pattern for Each Credential Type ### Database credentials → Payara JDBC Connection Pool Never do this: ```xml ``` Always do this: ```xml jdbc/coop ``` Configure the actual connection in the Payara Admin Console under **Resources → JDBC → Connection Pools**. ### API keys → Database config table API keys (e.g. Anthropic, Cloudflare) are stored in the application's configuration table, managed via the admin UI. Example: the AI Chat feature reads `AI Chat - Claude API Key` from the database at runtime. Never hardcode these in Java source or properties files. ### Local development overrides → ignored files If you need a local override (e.g. a different DB URL for your laptop), create: ``` src/main/resources/application-local.properties ``` This pattern is in `.gitignore`. Never commit it. --- ## What To Do If You Accidentally Commit a Secret **Act immediately — assume the credential is already compromised.** 1. **Rotate/revoke the credential right now.** Change the password, revoke the API key. Do not wait. 2. Notify the team lead. 3. Remove from git history: ```bash # Remove a specific file from all history git filter-repo --path path/to/secret-file --invert-paths ``` 4. Force-push after coordinating with the team. 5. File a GitHub issue documenting what was exposed and when it was rotated. > Note: Force-pushing does not protect anyone who already cloned or forked the repo before the fix. **Rotation is the only real remediation.** --- ## GitHub Repository Settings (Admins Only) These settings should be enabled in [github.com/hmislk/hmis](https://github.com/hmislk/hmis) → **Settings → Security and analysis**: | Setting | Status | |---|---| | Secret scanning | Should be enabled | | Push protection | Should be enabled — blocks pushes containing known secret patterns | | Dependabot alerts | Recommended | Push protection acts as a final safety net even if a developer's local hooks are not installed. --- ## Gitleaks False Positives If gitleaks blocks a commit that is not actually a secret (e.g. a test fixture, a placeholder value), you can add an allowlist entry in `.gitleaks.toml`: ```toml [allowlist] regexes = [ '''my_specific_false_positive_pattern''', ] ``` Always prefer fixing the allowlist over bypassing gitleaks with `--no-verify`. If you must bypass: **never use `--no-verify` on a commit that touches config files or connection strings.** --- ## Related - [GitHub issue #19638](https://github.com/hmislk/hmis/issues/19638) — tracking implementation - `.gitleaks.toml` — project-specific gitleaks rules - `.pre-commit-config.yaml` — pre-commit hook configuration - `scripts/install-dev-hooks.sh` — one-command developer setup - [Persistence Configuration Guide](https://github.com/hmislk/hmis/blob/development/developer_docs/deployment/persistence-verification.md)