Merge pull request #102 from talltechy/docs/update-copilot-instructions-secrets-policy

docs: Update Copilot instructions — secrets & PR checklist

Author: talltechy

.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.

.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 `<INSIGHTVM_API_PASSWORD>` 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

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

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_USERNAME>
+INSIGHTVM_API_PASSWORD=<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 `<INSIGHTVM_API_PASSWORD>` 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.