[injector] feat(shodan): create new injector (#106)

[Megafredo]

Proposed changes

• Implementation of 7 contracts for the Shodan injector

  • Cloud Provider Asset Discovery
  • Critical Ports And Exposed Admin Interface
  • Custom Query
  • CVE Enumeration
  • CVE Specific Watchlist (The only contract that requires a plan only available to academic users, Small Business API subscribers, and higher.)
  • Domain Discovery
  • IP Enumeration

• Currently, only the manual target type is functional.

Testing Instructions

1. Step-by-step how to test
2. Environment or config notes

Related issues

• Closes [Shodan]: Create the injector #106

Checklist

• I consider the submitted work as finished
• I tested the code for its functionality
• I wrote test cases for the relevant uses case
• I added/update the relevant documentation (either on github or on notion)
• Where necessary I refactored code to improve the overall quality
• For bug fix -> I implemented a test that covers the bug

Further comments

[Copilot]

Pull request overview

This PR introduces a new Shodan injector for the OpenAEV platform, enabling security reconnaissance and vulnerability scanning through the Shodan API.

Changes:

• Complete implementation of a new Shodan injector with 7 security scanning contracts (Cloud Provider Asset Discovery, Critical Ports, CVE Enumeration, Domain Discovery, Host Enumeration, Custom Query, and CVE Specific Watchlist)
• Configuration management using Pydantic with support for environment variables, .env files, and YAML configuration
• Rich-formatted output rendering system for scan results with tables, trees, and JSON views
• Docker deployment setup with multi-stage builds and docker-compose configuration

Reviewed changes

Copilot reviewed 38 out of 49 changed files in this pull request and generated 16 comments.

Show a summary per file

File	Description
shodan/shodan/services/client_api.py	Core API client for Shodan REST API with rate limiting, retry logic, and contract-specific query builders
shodan/shodan/services/utils.py	Rich-based output formatting utilities for rendering scan results with tables and trees
shodan/shodan/injector/openaev_shodan.py	Main injector orchestration logic handling message processing and output generation
shodan/shodan/contracts/*.py	Seven contract implementations defining fields, outputs, and trace configurations
shodan/shodan/models/configs/*.py	Pydantic-based configuration loaders with multi-source settings (env, yaml, .env)
shodan/pyproject.toml	Project metadata, dependencies, and tool configurations (black, isort, ruff, pytest)
shodan/Dockerfile	Multi-stage Docker build for Alpine-based deployment
shodan/docker-compose.yml	Container orchestration configuration with environment variable mapping
shodan/README.md	Comprehensive documentation covering deployment, configuration, and contract usage
shodan/tests/*	Empty test files (placeholders for future test implementation)

[RomuDeuxfois]

Tests:
Why we need to add an organization to run the Shodan contracts ? It's unclear to me.

• Cloud Provider Asset Discovery
  Manual with scanme.nmap.org, testphp.vulnweb.com
  Google provider -> Google,Microsoft,Amazon,Azure
  Inject in success 🟢
  Shodan result is 🟢

• Critical Ports And Exposed Admin Interface
  Manual with demo.elastic.co
  Port -> 9200
  Inject in success 🟢
  Shodan result is 🟢

• Custom Query
  Manual with GET and custom query product:"Apache httpd" port:80,443
  Inject in error 🔴

• CVE Enumeration
  Manual with scanme.nmap.org
  Inject in success 🟢
  I don't seen all the CVEs, maybe I will found it in my finding when the output parsing feature will be implemented.

• CVE Specific Watchlist
  Manual with CVE-2021-41773 and scanme.nmap.org
  Seems weird to required an host for this..
  Inject in success 🟢
  Shodan result is 🔴 -> The "vuln" filter is only available to academic users, Small Business API subscribers and higher. (400 - Bad Request)

• Domain Discovery
  Manual with vulnweb.com
  Seems weird to required an host for this..
  Inject in success 🟢
  Shodan result is 🟢

• Host Enumeration
  Manual with scanme.nmap.org
  Inject in success 🟢
  Shodan result is 🔴 -> Error: Invalid IP (404 - Not Found)

[ncarenton]

Thank you for your work on this PR @Megafredo! I noticed that there are currently no tests included for the Shodan injector. Are there plans to add tests as part of this PR, or will they be provided in a follow-up?

[jabesq]

After tests I've seen the following issue/misbehavior:

1. quota data are not updated

┣━━ scan_credits_remaining: None / None
┗━━ query_credits_remaining: None / None

2. When no are returned then the message should not display an empty array:

🌐 [SHODAN] Call API completed
┣━━ ✅ Call Success
┃   ┣━━ Total results: 0
┃   ┗━━ Details:
┃       ┗━━ • filigran.io → 0 results
┃           ┗━━ Request: GET 
┃               https://api.shodan.io/shodan/host/search?query=cloud.provider:Google,Microsoft,Amazon,Azure+hostname:filigran.io,*.filigran.io,org:fil
┃               igran.io
┗━━ ❌ Call Failed
    ┣━━ Total results: 0
    ┗━━ Details:

🔍 Asset(s) Not Created for filigran.io                                                                                                               
┏━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Hostnames              ┃ IP      ┃ Port        ┃ Cloud Provider                    ┃ OS      ┃ Vulnerabilities (score)                             ┃
┡━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
└────────────────────────┴─────────┴─────────────┴───────────────────────────────────┴─────────┴─────────────────────────────────────────────────────┘

[ncarenton]

⚠️ Do not merge before Monday, February 9th, as requested by @antoinemzs

[ncarenton]

⚠️ Do not merge before Monday, February 9th, as requested by @antoinemzs

Safe to merge at any time.