[TFT444]

Summary

• Adds POST /api/agent/query - a natural-language CSPM Q&A endpoint powered by a ReAct loop over 6 tool functions (get_findings, get_compliance_posture, get_attack_paths, explain_finding, suggest_remediation, scan_subscription)
• Adds openshield ask CLI command for terminal-based querying
• Adds an MCP server exposing all 6 tools to Claude Desktop and GitHub Copilot
• Hardens security: fail-closed tenant guard (empty tenant -> 403), subscription allowlist check on agent route, viewer-role exemption for Q&A POST, rollback safety on all DB tool functions, encoding fixes in tests

Changes by area

api/agent/

• agent.py - ReAct loop with guardrails (max iterations, prompt injection filter, confidence scoring)
• tools.py - 6 CSPM tool functions with tenant isolation; added db_conn.rollback() in all except blocks

api/routes/agent.py

• POST /api/agent/query with rate limiting (20 req/min), JWT auth, fail-closed tenant guard, subscription allowlist check

api/app.py

• _READ_ACCESSIBLE_POSTS exempts /api/agent/query from the write-role gate so viewer tokens can use Q&A

cli/ - openshield ask command with --subscription-id, --framework, --tenant-id flags

mcp_server.py - MCP server wiring all 6 tools for Claude Desktop / Copilot integration

tests/

• Full coverage: test_agent_tools, test_agent_loop, test_agent_route, test_cli_ask, test_mcp_server (38 tests)
• conftest: synthetic tenant injection hook so shared-secret-mode tests pass the tenant guard

Test plan

• python -m pytest tests/test_agent_tools.py tests/test_agent_loop.py tests/test_agent_route.py tests/test_cli_ask.py tests/test_mcp_server.py -q - 38 passed
• Tenant with no claim returns 403
• Viewer role can POST to /api/agent/query (read-only Q&A)
• Subscription not in allowlist returns 403

[github-actions]

Dependency Review

✅ No vulnerabilities or license issues or OpenSSF Scorecard issues found.

OpenSSF Scorecard

Package	Version	Score	Details
pip/aiohttp	3.14.5	Unknown	Unknown
pip/certifi	2026.10.23	🟢 6.5	Details Check Score Reason Code-Review 🟢 6 Found 4/6 approved changesets -- score normalized to 6 Security-Policy 🟢 10 security policy file detected Binary-Artifacts 🟢 10 no binaries found in the repo Maintained 🟢 8 8 commit(s) and 2 issue activity found in the last 90 days -- score normalized to 8 Token-Permissions 🟢 10 GitHub workflow tokens follow principle of least privilege Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Pinned-Dependencies 🟢 5 dependency not pinned by hash detected -- score normalized to 5 CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected License 🟢 9 license file detected Fuzzing ⚠️ 0 project is not fuzzed Signed-Releases ⚠️ -1 no releases found Branch-Protection ⚠️ 0 branch protection not enabled on development/release branches Packaging 🟢 10 packaging workflow detected SAST ⚠️ 0 SAST tool is not run on all commits -- score normalized to 0
pip/multidict	6.9.1	🟢 6.6	Details Check Score Reason Code-Review ⚠️ 0 Found 0/22 approved changesets -- score normalized to 0 Maintained 🟢 10 30 commit(s) and 26 issue activity found in the last 90 days -- score normalized to 10 Binary-Artifacts 🟢 10 no binaries found in the repo Dangerous-Workflow 🟢 10 no dangerous workflow patterns detected Token-Permissions ⚠️ 0 detected GitHub workflow tokens with excessive permissions Pinned-Dependencies ⚠️ 0 dependency not pinned by hash detected -- score normalized to 0 CII-Best-Practices ⚠️ 0 no effort to earn an OpenSSF best practices badge detected License 🟢 10 license file detected Fuzzing 🟢 10 project is fuzzed Security-Policy 🟢 10 security policy file detected Packaging 🟢 10 packaging workflow detected SAST 🟢 10 SAST tool is run on all commits Branch-Protection 🟢 3 branch protection is not maximal on development and all release branches Signed-Releases 🟢 8 5 out of the last 5 releases have a total of 5 signed artifacts.
pip/werkzeug	3.1.9	Unknown	Unknown

Scanned Files

• requirements.txt

[parthrohit22]

Reviewed 641b928. The overall shape is good: tenant and subscription come from the request rather than the model, scanning needs an operator role, and there’s a cap on iterations. But the tools can’t work against our database yet.

1. The queries target tables and columns that don’t exist. dev has no finding_lifecycles, finding_fingerprints, scan_rule_outcomes or compliance_scores table, and no tenant_id column anywhere. #326 · feat(automation): finding…’s schema doesn’t match either. It has fl.id, ff.id and resource_id_normalized, and no fl.finding_id, fl.outcome_id, fl.tenant_id, ff.fingerprint_id, ff.resource_id, or sro.outcome_id/severity/description/remediation.

Every tool falls into its except and returns db_error or an empty result. The agent then tells the user there are no findings, a false “all clear” from a security tool.
The tests use fake connections, so they don’t catch it. Please add a Postgres-backed test.

2. scan_subscription would fail and skips scan admission. scans has no tenant_id or created_at, requires started_at, and uses lowercase 'pending'. Please go through the existing scan-creation path so the idempotency and admission checks apply.

3. The MCP server bypasses API auth and roles. It connects straight to the database with one tenant from an environment variable. Anyone with the config can queue scans and read findings, and the subscription allowlist only covers scans. Please route it through the API with a token, or state this limitation clearly and remove the tenant-isolation claim from the README.

4. The local mcp/ package shadows the mcp SDK. The sys.path/sys.modules workaround is fragile. Please rename it, e.g. openshield_mcp/.

5. Malformed model output can cause a 500:

A bare JSON string makes "answer" in parsed a substring match, and then parsed["answer"] raises.
tuple(sorted(tool_args.items())) raises on list, dict or non-dict arguments.
The unparsed and no-key return paths skip clean_text.
confidence isn’t validated against HIGH/LOW.

6. Smaller items:

framework is accepted but never used.
--tenant-id is in the description but doesn’t exist.
openshield ask isn’t installed as a command. Please add it as a subcommand in OWASP/openshield#394’s openshield/cli.py.
The conftest change injects a tenant into the shared app fixture for the whole suite. Please limit it to the agent tests.
Drop the requirements* edits (OWASP/openshield#401 covers them) and fix Ruff lint, which is still red.