Feature/security gate

[JAugusto42]

Summary

This branch adds a new security gate command to the CLI, letting a pipeline check an asset's vulnerabilities against policy thresholds and fail the build if they're exceeded.

• New command: conviso security-gate, with two ways to run it:
  • Platform mode (default): asks the Conviso Platform for the PASS/FAIL decision (securityGateRun query). The platform applies its own configured rules and returns which vulnerabilities caused the failure.
  • Local rules mode (--rules-file): reads a YAML file with severity thresholds (e.g. "block if more than 0 critical, more than 5 high"), validates it against a JSON Schema, fetches live vulnerability counts (issuesStats), and evaluates the rules locally. Supports an optional grace period per severity (max_days_to_fix) so newly found issues aren't blocked immediately.
• Branch filtering (--branch / -b): scopes the evaluation to a specific branch, in both modes above.
  • Platform mode resolves the branch name to an ID first (new BranchLookup query), then passes it to the gate query.
  • Local rules mode passes the branch name directly to issuesStats.
  • Requires --company-id. Branch names are matched case-sensitively; an unknown branch fails with a clear error listing the available branches.
  • Legacy vulnerabilities with no branch recorded are excluded from the evaluation when --branch is used — the command warns about this explicitly every time.
• Output: results are shown in the terminal as Rich tables, and can optionally be written to a JSON file with --output.
• Error handling: any technical failure (network, timeout, auth, invalid asset/branch) always exits non-zero and is clearly labeled as a technical error — never confused with a "gate passed" result.
• Supporting changes:
  • Added jsonschema as a dependency (rules file validation).
  • client_graphql.py now supports a CONVISO_API_URL override (used to test against staging); production remains the default when unset.
  • Registered security-gate as a direct top-level command (not a subcommand group) and added it to the list of commands requiring authentication.
• Includes one unrelated, isolated one-line fix (separate commit f17a07b): corrected a pre-existing broken import in tests/test_batch_findings.py (from src.conviso... → from conviso...).

Usage

# Platform mode
conviso security-gate --asset-id 31894

# Local rules mode
conviso security-gate --asset-id 31894 --company-id 11 --rules-file rules.yaml

# Scoped to a branch
conviso security-gate --asset-id 31894 --company-id 11 --branch feature/my-feature

# Export full result as JSON
conviso security-gate --asset-id 31894 --output gate-result.json

Testing

• Automated Tests
  • Full suite: python -m pytest -v → 78/78 passing
  • Covers: YAML parsing and schema validation, rule evaluation (pass/fail/edge cases), SLA/timezone handling, both execution flows (mocked API), branch resolution (found/not found/case-sensitivity/network errors), CLI parameter validation, and formatter output.
• Manual Checks
  • Verified against staging (CONVISO_API_URL override):
    • Platform flow: PASS and FAIL scenarios, with and without --branch.
    • Local rules flow: PASS and FAIL scenarios, with and without --branch, including max_days_to_fix.
    • --branch without --company-id → exit 1, clear error.
    • Unknown branch → exit 1, lists available branches for the asset.
    • --output JSON export produces a complete result file.
    • Confirmed default (unset CONVISO_API_URL) still points to production.
    • Confirmed conviso security-gate --help shows options directly, with no subcommand required.

Notes

• Diagnostic script tools/check_security_gate_field.py was used during discovery to confirm securityGateRun and branch-related fields exist on the staging GraphQL schema before implementation started.
• Follow-up (out of scope for this PR): auto-detect the branch from common CI environment variables (GITHUB_REF_NAME, CI_COMMIT_REF_NAME) when --branch/CONVISO_BRANCH aren't set.
• Every execution with --branch makes one extra GraphQL call (BranchLookup) before the main gate query — accepted trade-off, not optimized in this PR.
• Full test plan, including rationale and edge cases, is checked in at docs/security_gate_test_plan.md.

Checklist

• Updated README/docs if user-facing changes (test plan document provided; README update tracked separately)
• Error handling returns non-zero exit on failures
  • Gate FAIL, branch not found, BranchLookup network/API errors, and missing --company-id all exit 1, with messages that distinguish technical errors from policy failures.