terraform-provider-shodan

Terraform Provider for Shodan

A Terraform provider for managing Shodan network alerts and domain monitoring configurations. This provider allows you to programmatically create, manage, and monitor network security alerts and domains using Shodan's powerful threat detection capabilities.

🚀 New Features:

• Domain Monitoring: Monitor domains for security threats with automatic IP resolution
• Configurable Request Intervals: Built-in rate limiting to ensure compliance with Shodan's API limits
• Multiple IP Support: Monitor multiple networks with single alerts

All API requests are automatically spaced apart to prevent hitting rate limits and ensure reliable operation. The request interval is configurable and defaults to 2 seconds between requests.

📋 Prerequisites

• Terraform >= 1.0
• Go >= 1.21 (for development)
• Shodan API Key

📖 Usage

Multiple IP Support

The provider now supports monitoring multiple IP addresses or network ranges in a single alert. You can specify:

• Single network: network = ["192.168.1.0/24"]
• Multiple networks: network = ["192.168.1.0/24", "10.0.0.0/8", "172.16.0.0/12"]
• Mixed IP types: network = ["203.0.113.1/32", "198.51.100.0/24", "192.0.2.1/32"]

This allows you to consolidate monitoring for multiple networks into fewer alerts while maintaining the same level of security monitoring.

Benefits of Multiple IP Support:

• Consolidated monitoring: Monitor multiple networks with a single alert
• Easier management: Fewer alert resources to manage in Terraform
• Cost effective: Reduce the number of Shodan alerts needed
• Flexible: Mix different types of IP ranges (single IPs, subnets, large networks)

Domain Monitoring

The provider now supports monitoring domains for security threats with automatic IP resolution:

# Monitor a domain for security threats
resource "shodan_domain" "example_monitoring" {
  domain      = "example.com"
  name        = "Example Domain Security Monitoring"
  description = "Monitor example.com for security threats"
  enabled     = true
  
  triggers = [
    "ai",
    "malware",
    "vulnerable",
    "new_service",
    "ssl_expired"
  ]
  
  notifiers = ["default"]
  
  # Enable Slack notifications
  slack_notifications = ["slack_12345"]
}

# Get domain information
data "shodan_domain" "example_info" {
  domain = "example.com"
}

How Domain Monitoring Works:

1. Automatic IP Resolution: The provider automatically resolves domains to IP addresses using Shodan's DNS API
2. Alert Creation: Creates a Shodan alert with the resolved IP addresses
3. Naming Convention: Uses __domain: {domain} format for automatic domain alerts
4. IP Monitoring: Monitors all IP addresses associated with the domain for security threats

Benefits of Domain Monitoring:

• Automatic IP Discovery: No need to manually track IP addresses for domains
• Dynamic Monitoring: Automatically adapts to IP address changes
• Comprehensive Coverage: Monitors all IP addresses associated with a domain
• Easy Management: Monitor domains instead of individual IP ranges
• Slack Integration: Direct Slack notification support for real-time alerts

Guides

The provider includes comprehensive guides to help you get started:

• Getting Started Guide - Basic setup, configuration, and first steps
• Domain Monitoring Guide - Learn how to monitor domains for security threats with automatic IP resolution
• Network Monitoring Guide - Create comprehensive security alerts for networks, subnets, and IP ranges

Provider Configuration

terraform {
  required_providers {
    shodan = {
      source = "AdconnectDevOps/shodan"
      version = "~> 0.1"
    }
  }
}

provider "shodan" {
  api_key = var.shodan_api_key
}

Request Interval Configuration

The provider automatically implements request spacing to ensure compliance with Shodan's API requirements:

• Configurable intervals: Request interval is configurable via the request_interval provider attribute
• Default behavior: Defaults to 2 seconds between requests if not specified
• Thread-safe: Concurrent requests are properly queued and spaced
• Flexible configuration: Can be adjusted based on your Shodan API plan limits
• Resource cleanup: Rate limiter resources are automatically cleaned up when the provider is closed

Configuration Examples

Default interval (2 seconds between requests):

provider "shodan" {
  api_key = var.shodan_api_key
  # request_interval defaults to 2 if not specified
}

Slower requests (5 seconds between requests):

provider "shodan" {
  api_key           = var.shodan_api_key
  request_interval  = 5  # 5 seconds between requests
}

Faster requests (1 second between requests):

provider "shodan" {
  api_key           = var.shodan_api_key
  request_interval  = 1  # 1 second between requests
}

This feature helps prevent API rate limit errors and ensures your Terraform operations complete successfully.

Finding Your Slack Notifier IDs

To configure Slack notifications, you need to get your Slack notifier IDs from your Shodan account:

1. Log into your Shodan account at shodan.io
2. Go to Account Settings → Notifications or Integrations
3. Find your Slack integration and note the notifier ID
4. Use this ID in your Terraform configuration:

variable "slack_notifier_ids" {
  description = "List of Slack notifier IDs from your Shodan account"
  type        = list(string)
  default     = ["xxxxxxxxxxx"]  # Your actual Slack notifier ID
  sensitive   = true
}

# Example: Using your actual Slack notifier ID
slack_notifier_ids = ["xxxxxxxxxxx"]  # Replace with your actual ID

💡 Pro Tip: You can have multiple Slack notifiers for different channels or teams. Just add more IDs to the list:

slack_notifier_ids = [
  "first-id-here",      # Main alerts channel
  "another-id-here",    # Secondary channel
  "third-id-here"       # Team-specific channel
]

Comprehensive Security Monitoring

# Single network range
resource "shodan_alert" "security_monitoring" {
  name        = "comprehensive-security-monitoring"
  network     = ["172.16.0.0/12"]
  description = "Comprehensive security monitoring for internal network"
  
  triggers = [
    "ai",
    "malware",
    "vulnerable",
    "new_service",
    "open_database",
    "ssl_expired",
    "iot"
  ]
  
  notifiers = ["default"]  # Email notifications
}

# Multiple specific IPs for targeted monitoring
resource "shodan_alert" "targeted_monitoring" {
  name        = "targeted-ip-monitoring"
  network     = ["203.0.113.1/32", "198.51.100.1/32", "192.0.2.1/32"]
  description = "Targeted monitoring for specific critical IPs"
  
  triggers = [
    "ai",
    "malware",
    "vulnerable",
    "new_service"
  ]
  
  notifiers = ["default"]
}

Slack Integration and Email Notifications

resource "shodan_alert" "multi_network_slack" {
  name        = "multi-network-slack-monitoring"
  network     = ["10.0.0.0/8", "172.16.0.0/12", "192.168.0.0/16"]
  description = "Multi-network monitoring with Slack alerts"
  
  triggers = [
    "ai",
    "malware",
    "vulnerable",
    "new_service"
  ]
  
  notifiers = ["default"]
  
  slack_notifications = var.slack_notifier_ids
}

📚 Resources

shodan_alert

Arguments

Attributes

shodan_domain

Arguments

Attributes

📊 Data Sources

shodan_domain

Arguments

Attributes

Available Trigger Rules

The following trigger rules are available for Shodan alerts:

• end_of_life - End of life software detected
• industrial_control_system - Industrial control system detected
• internet_scanner - Internet scanner detected
• iot - Internet of Things device detected
• malware - Malware detected
• new_service - New service detected
• open_database - Open database detected
• ssl_expired - SSL certificate expired
• uncommon - Uncommon service detected
• uncommon_plus - Extended uncommon service detection
• vulnerable - Vulnerable service detected
• vulnerable_unverified - Unverified vulnerable service

📧 Available Notifiers

• default - Default email notifier (configured in Shodan account)
• slack - Slack integration (configured in Shodan account)

Getting Slack Notifier IDs

To use Slack notifications, you need to get your Slack notifier ID from your Shodan account:

1. Go to your Shodan account settings
2. Navigate to "Notifications" or "Integrations"
3. Find your Slack integration and note the notifier ID
4. Use this ID in your Terraform configuration:

variable "slack_notifier_ids" {
  description = "List of Slack notifier IDs from your Shodan account"
  type        = list(string)
  default     = ["xxxxxxxxxxx"]  # Your actual Slack notifier ID
  sensitive   = true
}

resource "shodan_alert" "example" {
  # ... other configuration ...
  
  slack_notifications = var.slack_notifier_ids
}

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Shodan for providing the security monitoring API
• HashiCorp for the Terraform plugin framework
• The open-source community for inspiration and support

📞 Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Releases: GitHub Releases

Note: This provider is not officially affiliated with Shodan. It's a community-driven project to bring Shodan's powerful security monitoring capabilities to Terraform workflows.