From 935086edc192ae7897b39d8b6fda8f5b2eddfc6b Mon Sep 17 00:00:00 2001 From: Matt Wyen Date: Mon, 13 Oct 2025 17:56:42 -0400 Subject: [PATCH 1/3] docs(copilot): add secrets policy, PR checklist, and SSL guidance --- .github/copilot-instructions.md | 58 ++++++++++++++++++++++++++++----- 1 file changed, 50 insertions(+), 8 deletions(-) diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md index 8b776bf..0911c99 100644 --- a/.github/copilot-instructions.md +++ b/.github/copilot-instructions.md @@ -62,20 +62,62 @@ source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install dependencies pip install -r requirements.txt -# Configure environment +# Configure environment (SECURE) cp .env.example .env -# Edit .env with credentials +# Create a local `.env` from `.env.example` for development only. Do NOT commit real credentials. +# For production or CI, set secrets using the platform's secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.) +# Never embed API credentials, tokens, or passwords in code, config files checked into source control, or documentation examples. ``` -### Required Environment Variables +### Required Environment Variables (DO NOT HARD-CODE SECRETS) -```bash -INSIGHTVM_API_USERNAME=your_username -INSIGHTVM_API_PASSWORD=your_password -INSIGHTVM_BASE_URL=https://your-console:3780 -INSIGHTVM_VERIFY_SSL=false # For self-signed certificates +Provide the following configuration via environment variables or a secret manager. Examples in documentation should show how to reference these variables (e.g. `os.getenv(...)`) but must never include real credential values. + +- `INSIGHTVM_API_USERNAME` — InsightVM API username (string); supply via environment or secret manager. +- `INSIGHTVM_API_PASSWORD` — InsightVM API password (secret); store in a secret manager and reference via env var in CI. Never commit this value. +- `INSIGHTVM_BASE_URL` — Full console base URL (include scheme and port), e.g. `https://console.example:3780`. +- `INSIGHTVM_VERIFY_SSL` — Optional boolean; default `true`. Set to `false` only in trusted development/testing environments when using self-signed certificates. + +Best practice: Use CI secrets or an external secret manager for production systems and avoid committing `.env` files to the repository. + +Secrets Policy (short): +- Never include actual API keys, passwords, tokens, or private keys in source code, documentation, or examples. +- When examples require secrets, use placeholders like `` or show reading from env vars only. +- Add secret-scanning in CI and pre-commit hooks. Recommended tools: gitleaks, detect-secrets. (Guidance only — do not add secret values here.) + +## PR & Commit Checklist (recommended) + +Before opening a pull request, ensure: + +- No secrets or hardcoded credentials are introduced in the diff. +- Code formatting and static checks pass (black, flake8, mypy). +- Tests cover new functionality; tests use mocks/fixtures for external API calls. +- Documentation and migration notes updated for any public API or behavior changes. +- Add a short security note in the PR description when changes touch auth, secrets, or SSL handling. + +## Examples & Tests (no secrets) + +- Example code should demonstrate how to read configuration from environment variables, e.g.: + +```python +import os + +username = os.getenv("INSIGHTVM_API_USERNAME") +password = os.getenv("INSIGHTVM_API_PASSWORD") +base_url = os.getenv("INSIGHTVM_BASE_URL") ``` +- Integration or example scripts that require real credentials should never be committed. Tests should use `tests/conftest.py` fixtures and mocked API responses instead of real endpoints. + +## API Naming & Compatibility Guidance + +- Avoid introducing method names that conflict with `BaseAPI` (for example, do not add `get`, `update`, or `delete` methods to subclasses if those signatures would shadow incompatible parent methods). +- For the Scan Engines client prefer explicit method names such as `get_engine`, `update_engine`, and `delete_engine` to avoid inheritance conflicts. When renaming public methods, include a deprecation wrapper and add a migration note in `MIGRATION.md` and the module's docs. + +## SSL Verification Guidance + +- Default `INSIGHTVM_VERIFY_SSL` to `true`. Disabling SSL verification (`false`) is allowed only in trusted development or test environments with self-signed certificates and must be documented. Clearly warn users in docs about the security implications of disabling certificate verification. + ## Coding Standards ### Python Style Guide From be84445688512109fa75be30d4da47c090f3727a Mon Sep 17 00:00:00 2001 From: Matt Wyen Date: Mon, 13 Oct 2025 18:15:50 -0400 Subject: [PATCH 2/3] docs: reference Copilot guidance in README and MIGRATION --- MIGRATION.md | 16 +++++++++++----- README.md | 25 ++++++++++++++++++++----- 2 files changed, 31 insertions(+), 10 deletions(-) diff --git a/MIGRATION.md b/MIGRATION.md index 0a78546..fb8a2f8 100644 --- a/MIGRATION.md +++ b/MIGRATION.md @@ -28,14 +28,20 @@ ivm_username=myuser ivm_password=mypass ``` -**v2.0 `.env` format:** +**v2.0 `.env` format (DO NOT HARD-CODE SECRETS):** +Provide these variables via environment or a secret manager. Example usages in docs should reference env vars (e.g. `os.getenv(...)`) and must never include real credential values. + ```bash -INSIGHTVM_API_USERNAME=myuser -INSIGHTVM_API_PASSWORD=mypass -INSIGHTVM_BASE_URL=https://192.168.10.190:3780 -INSIGHTVM_VERIFY_SSL=false # if using self-signed certificates +# INSIGHTVM_API_USERNAME (string) - set in env or secret manager +# INSIGHTVM_API_PASSWORD (secret) - store in secret manager; do NOT commit +# INSIGHTVM_BASE_URL (string) - full console URL, e.g. https://console.example:3780 +# INSIGHTVM_VERIFY_SSL (bool) - default true; set to false only for trusted self-signed certs ``` +**Security note:** Use CI secrets or an external secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.) for production; do not store credentials in the repository. + +**Copilot guidance:** When using GitHub Copilot to generate or edit code that interacts with authentication or configuration, consult `.github/copilot-instructions.md` for repository-specific guidance on secrets, environment variables, and example generation. Do not add real credentials or sensitive values to code or documentation. + **Migration script for .env:** ```bash # Combine host and port into base URL diff --git a/README.md b/README.md index 91032f7..57d2c1b 100644 --- a/README.md +++ b/README.md @@ -41,18 +41,24 @@ pip install -r requirements.txt ### Configuration -Create a `.env` file in the project root (see `.env.example` for template): +Create a `.env` file in the project root (see `.env.example` for template). + +Do NOT commit real credentials. Use `.env.example` as a template for local development only, and use your platform's secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.) for CI and production settings. + +Example placeholders (do not commit real values): ```bash -# Rapid7 InsightVM API -INSIGHTVM_API_USERNAME=your_username -INSIGHTVM_API_PASSWORD=your_password +# Rapid7 InsightVM API (placeholders - DO NOT COMMIT) +INSIGHTVM_API_USERNAME= +INSIGHTVM_API_PASSWORD= INSIGHTVM_BASE_URL=https://your-console:3780 # SSL Configuration (optional) -INSIGHTVM_VERIFY_SSL=false # Set to false for self-signed certificates +INSIGHTVM_VERIFY_SSL=false # Set to false only for trusted development/testing environments ``` +See `.github/copilot-instructions.md` for Copilot-specific guidance on generating examples and handling secrets safely. + ### Basic Usage ```python @@ -292,6 +298,15 @@ except requests.exceptions.RequestException as e: - **HTTPBasicAuth** - Industry-standard authentication pattern - **Timeout Configuration** - Prevent hanging connections +### Secrets Policy + +This project enforces a strict secrets policy to avoid accidental credential leaks: + +- Never store API keys, passwords, tokens, or private keys in the repository or documentation examples. +- Examples should reference environment variables or secret manager usage (e.g. `os.getenv('INSIGHTVM_API_PASSWORD')`) and use placeholders such as `` when needed. +- For development, use a local `.env` (gitignored). For CI and production, use a secret manager (GitHub Secrets, AWS Secrets Manager, Azure Key Vault, etc.). +- See `.github/copilot-instructions.md` for additional guidance used by GitHub Copilot when generating or editing code. + ### Security Considerations ⚠️ **Self-Signed Certificates**: When using `verify_ssl=False`, you bypass SSL certificate validation. Only use this in trusted environments with self-signed certificates. From c6d24e266df7b8705fc9fd21acca45ddb4da12f9 Mon Sep 17 00:00:00 2001 From: Matt Wyen Date: Mon, 13 Oct 2025 18:18:18 -0400 Subject: [PATCH 3/3] docs: add PR template with security checklist --- .github/PULL_REQUEST_TEMPLATE.md | 19 +++++++++++++++++++ 1 file changed, 19 insertions(+) create mode 100644 .github/PULL_REQUEST_TEMPLATE.md diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md new file mode 100644 index 0000000..5fd13ea --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -0,0 +1,19 @@ +## Description +Provide a short, descriptive summary of your changes. + +## Related Issue +Fixes # (if applicable) + +## Changes Made +- Change 1 +- Change 2 + +## Security Checklist +- [ ] No secrets or hardcoded credentials are introduced in this PR +- [ ] Lint & type checks run (black, flake8, mypy) +- [ ] Tests added/updated where applicable (use mocks/fixtures for external APIs) +- [ ] Documentation and migration notes updated for any public API or behavior changes +- [ ] Security impact reviewed by a maintainer (if applicable) + +## Reviewer Suggestions +Please add reviewers (maintainers/security team) for final approval.