# 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)