feat: add repository pre-commit hooks

[rinadavidyuk826-sudo]

Summary

• add a repository-level .pre-commit-config.yaml with YAML hygiene, merge-conflict, whitespace, detect-secrets, ruff, and mypy hooks
• add a checked-in .secrets.baseline so existing fixtures and sample data do not block new diffs
• update the root CONTRIBUTING.md with pre-commit setup, validation commands, and repository-level hook behavior

Closes #401.

Validation

• pre-commit run --all-files

[github-actions]

Welcome to the Agent Governance Toolkit! Thanks for your first pull request.
Please ensure tests pass, code follows style (ruff check), and you have signed the CLA.
See our Contributing Guide.

[github-actions]

🤖 AI Agent: code-reviewer

Review Summary

This pull request introduces a repository-level .pre-commit-config.yaml file to enforce code quality and security checks, along with a .secrets.baseline file to manage existing secrets in the repository. Additionally, it updates the CONTRIBUTING.md file to guide contributors on setting up and using the pre-commit hooks.

While this is a valuable addition to the repository, there are several areas that need attention to ensure the changes are robust, secure, and maintainable.

---

🔴 CRITICAL

1. Potential Exposure of Secrets in .secrets.baseline

   • The .secrets.baseline file contains hashed secrets but does not provide clarity on whether these secrets are still valid or have been rotated. If any of these secrets are still valid, they could pose a security risk.
   • Action Required: Ensure that all secrets identified in the .secrets.baseline file are invalidated and rotated. Document this process in the CONTRIBUTING.md file to ensure contributors understand how to handle secrets.

2. Exclusion of Critical Directories in check-yaml Hook

   • The check-yaml hook excludes several directories, including packages/agent-mesh/charts, packages/agent-os/templates/policies, and others. YAML files in these directories may still contain critical configuration or policy definitions that require validation.
   • Action Required: Reassess the exclusions for the check-yaml hook. If these directories contain YAML files that are critical for the application, they should not be excluded from validation.

3. Inadequate Secret Detection Scope

   • The detect-secrets hook is configured with a baseline file, but it does not specify any additional arguments to enhance detection (e.g., custom plugins, stricter entropy thresholds).
   • Action Required: Consider enabling stricter detection rules or additional plugins to ensure comprehensive secret detection. For example, lower the entropy thresholds for Base64HighEntropyString and HexHighEntropyString detectors.

---

🟡 WARNING

1. Potential Breaking Changes in Contributor Workflow

   • Introducing pre-commit hooks can disrupt existing workflows for contributors who are not familiar with pre-commit. This could lead to frustration or reduced productivity.
   • Action Required: Ensure that the CONTRIBUTING.md file provides clear, step-by-step instructions for installing and using pre-commit. Include troubleshooting tips for common issues.

2. Hardcoded Paths in ruff and mypy Hooks

   • The ruff and mypy hooks are configured to target specific directories (packages/agent-runtime/src/agent_runtime). If the directory structure changes, these configurations will break.
   • Action Required: Consider using dynamic path resolution or a more generic pattern to avoid hardcoding paths. For example, use packages/**/src/**/*.py to include all Python files in src directories.

---

💡 SUGGESTIONS

1. Add a Hook for Pydantic Model Validation

   • Given the importance of type safety and Pydantic model validation in this repository, consider adding a custom pre-commit hook to validate Pydantic models during development.
   • Suggestion: Use tools like pydantic-check or write a custom script to validate Pydantic models and include it as a pre-commit hook.

2. Add a Hook for Dependency Updates

   • To ensure dependencies are up-to-date and secure, consider adding a pre-commit hook for dependency updates (e.g., pip-audit or safety).
   • Suggestion: Add a safety or pip-audit hook to check for known vulnerabilities in dependencies.

3. Document Hook Behavior

   • The CONTRIBUTING.md file should include a detailed explanation of each hook, its purpose, and how contributors can resolve issues flagged by the hooks.
   • Suggestion: Add a table or section in CONTRIBUTING.md that describes each hook and its role in maintaining code quality and security.

4. Automate Baseline Updates

   • Managing the .secrets.baseline file manually can be error-prone. Automate its updates to ensure it remains accurate and up-to-date.
   • Suggestion: Add a script or CI job to periodically update the .secrets.baseline file and verify that no new secrets are introduced.

5. Consider Adding a Hook for Formatting

   • While ruff-format is included, consider adding a dedicated black or isort hook for formatting to ensure consistent code style across the repository.
   • Suggestion: Add black and/or isort hooks to the .pre-commit-config.yaml file.

---

Additional Notes

• The .pre-commit-config.yaml file is well-structured and includes a good selection of hooks for code quality and security.
• The inclusion of detect-secrets is a positive step toward improving security, but its configuration needs refinement to maximize its effectiveness.
• The CONTRIBUTING.md update is a thoughtful addition, but it could benefit from more detailed instructions and examples.

---

Summary of Required Actions

1. 🔴 Ensure all secrets in .secrets.baseline are invalidated and rotated.
2. 🔴 Reassess the exclusions for the check-yaml hook.
3. 🔴 Enhance the detect-secrets configuration with stricter rules and additional plugins.
4. 🟡 Provide clear instructions in CONTRIBUTING.md for setting up and using pre-commit.
5. 🟡 Avoid hardcoding paths in ruff and mypy hooks; use dynamic or generic patterns.

Summary of Suggested Improvements

1. 💡 Add a pre-commit hook for Pydantic model validation.
2. 💡 Add a pre-commit hook for dependency updates (safety or pip-audit).
3. 💡 Document the purpose and behavior of each pre-commit hook in CONTRIBUTING.md.
4. 💡 Automate updates to the .secrets.baseline file.
5. 💡 Add black and/or isort hooks for consistent code formatting.

By addressing these issues and suggestions, the repository will benefit from improved security, maintainability, and contributor experience.

[github-actions]

🤖 AI Agent: security-scanner — Security Review of PR: `feat: add repository pre-commit hooks`

Security Review of PR: feat: add repository pre-commit hooks

This PR introduces a .pre-commit-config.yaml file to enforce code hygiene, detect secrets, and validate Python code using tools like detect-secrets, ruff, and mypy. Additionally, a .secrets.baseline file is added to allow pre-existing secrets in the repository to be ignored by detect-secrets.

---

Security Findings

1. Credential Exposure in .secrets.baseline

• Severity: 🔴 CRITICAL
• Issue: The .secrets.baseline file contains hashed secrets for various files in the repository. While these are hashed, the presence of this file in the repository may inadvertently expose sensitive information if the hashes are reversible or if the original secrets are still present in the repository.
• Attack Vector: An attacker could use the .secrets.baseline file to identify sensitive files and attempt to reverse the hashes or locate the original secrets in the repository's history.
• Recommendation:
  1. Audit and Remove Secrets: Ensure that all secrets in the repository are rotated and removed from the codebase, including the Git history.
  2. Restrict .secrets.baseline: Add .secrets.baseline to .gitignore and store it securely outside the repository. Alternatively, use a secure secrets management system to handle secrets.
  3. Verify Baseline: Regularly review and update the .secrets.baseline file to ensure it does not contain sensitive information.

---

2. Potential for False Negatives in detect-secrets

• Severity: 🟠 HIGH
• Issue: The detect-secrets configuration relies on a baseline file to ignore pre-existing secrets. If new secrets are added to the repository in files already listed in the baseline, they may not be detected.
• Attack Vector: An attacker could intentionally add secrets to files already listed in the baseline, bypassing detection.
• Recommendation:
  1. Enable Verification: Use the --verify flag with detect-secrets to ensure that secrets in the baseline are still valid and not tampered with.
  2. Regular Scans: Periodically re-scan the repository without the baseline to detect any new secrets.
  3. Granular Baseline: Limit the baseline to specific lines or sections of files, rather than entire files, to reduce the risk of false negatives.

---

3. Dependency Trust Chain Weakness

• Severity: 🟠 HIGH
• Issue: The .pre-commit-config.yaml file references external repositories (e.g., https://github.com/pre-commit/pre-commit-hooks, https://github.com/Yelp/detect-secrets, etc.) without verifying their integrity (e.g., using commit hashes or signed tags).
• Attack Vector: If any of these repositories are compromised or if a malicious actor gains control, they could inject malicious code into the pre-commit hooks.
• Recommendation:
  1. Pin Versions: Use specific commit hashes instead of branch names or tags (e.g., rev: v6.0.0 → rev: <specific_commit_hash>).
  2. Verify Integrity: Use tools like sigstore/cosign to verify the integrity of the dependencies.
  3. Periodically Audit Dependencies: Regularly review the dependencies for security vulnerabilities or suspicious changes.

---

4. Exclusion Rules in check-yaml

• Severity: 🟡 MEDIUM
• Issue: The check-yaml hook excludes several directories (e.g., packages/agent-mesh/charts, packages/agent-os/templates/policies/, etc.) from YAML validation. This could allow malformed or malicious YAML files to bypass validation.
• Attack Vector: An attacker could exploit this exclusion to introduce malicious or malformed YAML files into the excluded directories, potentially leading to configuration issues or vulnerabilities.
• Recommendation:
  1. Review Exclusions: Ensure that the excluded directories do not contain YAML files critical to the security or functionality of the system.
  2. Add Targeted Validation: If exclusions are necessary, implement alternative validation mechanisms for the excluded directories.

---

5. Potential for Race Conditions in Pre-Commit Hooks

• Severity: 🟡 MEDIUM
• Issue: Pre-commit hooks are executed locally, and their enforcement relies on developers running them before committing. If a developer bypasses the hooks (e.g., by using git commit --no-verify), the checks will not be applied.
• Attack Vector: A malicious or careless developer could bypass the pre-commit hooks, introducing vulnerabilities or unvalidated code into the repository.
• Recommendation:
  1. Enforce Hooks in CI/CD: Ensure that the CI/CD pipeline runs the same checks as the pre-commit hooks to catch any bypassed issues.
  2. Educate Developers: Provide clear documentation and training on the importance of running pre-commit hooks.

---

Additional Observations

1. Documentation Update:

   • The PR includes updates to the CONTRIBUTING.md file to guide developers on setting up and using the pre-commit hooks. This is a good practice and should be encouraged.

2. Tool Versions:

   • The tools used in the pre-commit hooks (e.g., ruff, mypy, detect-secrets) are pinned to specific versions. This is a good practice to ensure consistency across developer environments.

3. Baseline File Size:

   • The .secrets.baseline file is quite large (826 lines). This may indicate a significant number of secrets in the repository, which could pose a security risk. A thorough audit is recommended.

---

Summary of Findings

Finding	Severity	Recommendation
Credential exposure in .secrets.baseline	🔴 CRITICAL	Remove secrets from the repository, restrict .secrets.baseline, and rotate credentials.
Potential false negatives in detect-secrets	🟠 HIGH	Enable verification, perform regular scans, and use granular baselines.
Dependency trust chain weakness	🟠 HIGH	Pin dependencies to specific commit hashes and verify their integrity.
Exclusion rules in check-yaml	🟡 MEDIUM	Review exclusions and implement alternative validation for excluded directories.
Potential for race conditions in hooks	🟡 MEDIUM	Enforce hooks in CI/CD and educate developers on their importance.

---

Final Recommendation

Before merging this PR, address the critical and high-severity findings. Specifically:

1. Remove secrets from the repository and secure the .secrets.baseline file.
2. Pin dependencies to specific commit hashes and verify their integrity.
3. Review and tighten the exclusions in the check-yaml hook.

After addressing these issues, this PR can be safely merged.

[imran-siddique]

Closing — pre-commit hooks were already merged in #431 and this PR has merge conflicts. Thank you for the contribution @rinadavidyuk826-sudo! Your other PRs (#449, #451, #452) are great — we'll review those.