pwap/.git-hooks/README.md

Git Hooks - PezkuwiChain

=Ë Overview

This directory contains Git hook templates that help prevent security issues and maintain code quality.

---

=' Installation

Quick Install (Recommended)

Run this command from the project root:

cp .git-hooks/pre-commit.example .git/hooks/pre-commit
chmod +x .git/hooks/pre-commit

Verify Installation

# Check if hook is installed
ls -la .git/hooks/pre-commit

# Test the hook
git add .
git commit -m "test" --dry-run

---

=Ú Available Hooks

pre-commit

Purpose: Prevents committing sensitive data and enforces code quality

Checks:

• L Blocks .env files from being committed
• L Blocks files with sensitive patterns (passwords, API keys, etc.)
• L Blocks secret files (.key, .pem, .cert, etc.)
•   Warns about large files (>500KB)
•   Warns about debug code (console.log, debugger)
•   Warns about hardcoded credentials

Example output:

=
 Running pre-commit security checks...
Checking for .env files...
Scanning for sensitive patterns...
Checking for secret files...
Checking for large files...
Checking for debug code...
 All security checks passed!

---

=à Configuration

Bypass Hook (Not Recommended)

If you absolutely need to bypass the hook:

git commit --no-verify -m "message"

  WARNING: Only bypass if you're sure there are no secrets!

Customize Checks

Edit .git-hooks/pre-commit.example and adjust:

• PATTERNS - Secret detection patterns
• SECRET_FILES - File patterns to block
• MAX_FILE_SIZE - Maximum file size in KB
• DEBUG_PATTERNS - Debug code patterns

---

>ê Testing

Test with Sample Commits

# Test 1: Try to commit .env (should fail)
echo "SECRET=test" > .env
git add .env
git commit -m "test"
# Expected: L ERROR: Attempting to commit .env file!

# Test 2: Try to commit hardcoded password (should fail)
echo 'const password = "mysecret123"' >> test.ts
git add test.ts
git commit -m "test"
# Expected: L ERROR: Potential secrets detected!

# Test 3: Normal commit (should pass)
echo 'const x = 1' >> test.ts
git add test.ts
git commit -m "test"
# Expected:  All security checks passed!

---

=

What Each Check Does

1. .env File Check

# Blocks any .env file
.env
.env.local
.env.production
.env.staging

2. Sensitive Pattern Detection

Searches for patterns like:

• password = "..."
• api_key = "..."
• secret = "..."
• token = "..."
• Private key headers
• AWS access keys

3. Secret File Detection

Blocks files matching:

• *.key, *.pem, *.cert
• *.p12, *.pfx
• *secret*, *credential*
• .npmrc, .dockercfg

4. Large File Warning

Warns if file is larger than 500KB:

   WARNING: Large file detected: image.png (1024KB)
Consider using Git LFS for large files

5. Debug Code Detection

Warns about:

• console.log()
• debugger
• TODO security
• FIXME security

6. Hardcoded Credentials Check

Special check for AuthContext.tsx:

// L BAD - Will be blocked
const password = "mysecret123"

//  GOOD - Will pass
const password = import.meta.env.VITE_PASSWORD

---

=¨ Troubleshooting

Hook Not Running

# Check if hook exists
ls -la .git/hooks/pre-commit

# Check if executable
chmod +x .git/hooks/pre-commit

# Verify hook content
cat .git/hooks/pre-commit

False Positives

If the hook incorrectly flags a file:

1. Review the pattern that triggered
2. Confirm the file is safe
3. Use --no-verify to bypass (with caution)
4. Update the pattern in .git-hooks/pre-commit.example

Hook Errors

# If hook fails to run
bash -x .git/hooks/pre-commit

# Check for syntax errors
bash -n .git/hooks/pre-commit

---

=Ê Integration with CI/CD

The pre-commit hook works alongside:

GitHub Actions

• .github/workflows/security-check.yml - Automated security scanning
• Runs on every PR and push to main
• Catches issues missed locally

Pre-push Hook (Optional)

You can also add a pre-push hook:

# .git-hooks/pre-push.example
#!/bin/bash
npm test
npm run lint

---

= Best Practices

1. Install hooks immediately after cloning the repo
2. Never use --no-verify unless absolutely necessary
3. Keep hooks updated - run git pull regularly
4. Test hooks before committing important changes
5. Report false positives to improve the hook

---

=Ú Additional Resources

Git Hooks Documentation

• Git Hooks Official Docs
• Pre-commit Framework

Security Tools

• git-secrets
• gitleaks
• TruffleHog

---

<˜ Support

If you encounter issues:

1. Check this README
2. Review SECURITY.md in project root
3. Contact: security@pezkuwichain.io

---

Last Updated: October 28, 2024