feat(shodan): add TTP mapping and argumentType on ip/vulnerability fields (#405)

[Sébastien MIGUEL (Seb-MIGUEL)]

Summary

Closes #405

• contract_attack_patterns_external_ids=["T1596.005"] (Search Open Technical Databases: Scan Databases) on all 7 shodan contracts.
• argumentType=PrimitiveType.IPv4 on the "IP" field (ip_enumeration) - picked as the practical default since PrimitiveType carries one value per field and Shodan's IP-typed outputs are overwhelmingly IPv4; an IPv6 finding will not auto-link here (flagged rather than silently assumed).
• argumentType=PrimitiveType.CVE on the "Vulnerability" field (cve_specific_watchlist) - it holds a CVE id despite the generic label.
• hostname/organization/custom_query stay text: hostname's fit needs confirming (the internal trace config calls it plural "hostnames" - one value or a CSV list?), organization has no org-shaped finding produced anywhere today, custom_query is a raw query-language string.
• Regression tests: test_argument_type.py pins the two typed fields; test_ttp_mapping.py asserts every built contract carries exactly ["T1596.005"] (added following review).

Test plan

• pytest tests/ - 31/31 passing locally, Test shodan green in CI

Notes

• The Test nuclei / ci/circleci: test-nuclei failures are unrelated to this PR: client-python main recently added ContractElement.argumentType (feat(client): add PrimitiveType and ContractElement.argumentType (#334) client-python#333), which changed the serialized contract JSON and broke nuclei's exact-payload sync tests on every branch of this repo. The nuclei fixture update lands with the feat/nuclei-action-output-and-ttp-mapping PR.

[Copilot]

Pull request overview

This PR updates the Shodan injector’s contract metadata to support the platform rollout for (1) input argument typing (for chaining) and (2) MITRE ATT&CK technique mapping, as tracked by #405.

Changes:

• Add argumentType typing to the Shodan ip_enumeration.ip field (PrimitiveType.IPv4) and cve_specific_watchlist.vulnerability field (PrimitiveType.CVE).
• Add contract_attack_patterns_external_ids=["T1596.005"] to all 7 Shodan contracts.
• Add a focused test validating the new argumentType values on the two affected fields.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
shodan/tests/shodan_contracts/test_argument_type.py	Adds tests asserting argumentType is set for the IP and vulnerability inputs.
shodan/shodan/contracts/ip_enumeration/contract.py	Types the ip input as PrimitiveType.IPv4 and adds TTP mapping on the contract.
shodan/shodan/contracts/cve_specific_watchlist/contract.py	Types the vulnerability input as PrimitiveType.CVE and adds TTP mapping on the contract.
shodan/shodan/contracts/domain_discovery/contract.py	Adds contract_attack_patterns_external_ids mapping to the contract.
shodan/shodan/contracts/cve_enumeration/contract.py	Adds contract_attack_patterns_external_ids mapping to the contract.
shodan/shodan/contracts/custom_query/contract.py	Adds contract_attack_patterns_external_ids mapping to the contract.
shodan/shodan/contracts/critical_ports_and_exposed_admin_interface/contract.py	Adds contract_attack_patterns_external_ids mapping to the contract.
shodan/shodan/contracts/cloud_provider_asset_discovery/contract.py	Adds contract_attack_patterns_external_ids mapping to the contract.

[Samuel Hassine (SamuelHassine)]

Reviewed the full changed files independently and drove the follow-up fixes on the branch. The TTP choice (T1596.005, Search Open Technical Databases: Scan Databases) is the canonical technique for Shodan queries and fits all 7 contracts; the two argumentType picks (IPv4 on ip_enumeration, CVE on cve_specific_watchlist) are correct against pyoaev PrimitiveType, and the fields deliberately left as text are well justified in the description. A TTP regression test now pins the mapping across all contracts. Test shodan, linter and ensure_formatting are green; the Test nuclei failures are external to this PR (client-python main added ContractElement.argumentType, which changed serialized contract JSON and broke nuclei exact-payload sync tests on every branch; the fixture update lands with PR #410). Approving.

[Samuel Hassine (SamuelHassine)]

Review and fix summary

Fixes pushed (f5dba26, signed):

• Added tests/shodan_contracts/test_ttp_mapping.py: builds the full contract set and asserts every contract carries exactly ["T1596.005"] (addresses the Copilot review comment; mirrors the stratus TTP test precedent).
• Removed a dangling reference to a non-existent docs/specs/ file from the test_argument_type.py docstring.
• Tightened the argumentType comment in ip_enumeration/contract.py.

Review threads: 1 inline comment (Copilot) - implemented, replied, resolved. 0 unresolved threads remain.

Verification: 31/31 tests pass locally and in CI (Test shodan green). Black/isort/flake8 clean on the touched files. PR title matches the repo convention and the description was re-flowed to reflect the final state.

Remaining blocker (external): Test nuclei and ci/circleci: test-nuclei fail on every branch of this repo since client-python main added ContractElement.argumentType (changed serialized contract JSON, breaking nuclei exact-payload sync tests). The nuclei fixture update lands with PR #410; once merged, a rebase or re-run turns this PR fully green. Nothing in this shodan-only diff can or should fix it. CLA check is green (organization member).