https://github.com/KaanSK/shomon

Shodan Monitoring integration for TheHive.
https://github.com/KaanSK/shomon

golang incident-management incident-response incident-response-tooling security security-tools shodan thehive

Last synced: about 7 hours ago
JSON representation

Shodan Monitoring integration for TheHive.

• Host: GitHub
• URL: https://github.com/KaanSK/shomon
• Owner: KaanSK
• License: mit
• Created: 2020-05-29T18:20:25.000Z (over 4 years ago)
• Default Branch: master
• Last Pushed: 2022-07-31T07:17:03.000Z (over 2 years ago)
• Last Synced: 2024-06-20T08:16:53.091Z (5 months ago)
• Topics: golang, incident-management, incident-response, incident-response-tooling, security, security-tools, shodan, thehive
• Language: Go
• Homepage:
• Size: 257 KB
• Stars: 131
• Watchers: 6
• Forks: 19
• Open Issues: 0
• Metadata Files:
  • Readme: README.md
  • Funding: .github/FUNDING.yml
  • License: LICENSE

Awesome Lists containing this project

• awesome-ip-search-engines - Shomon (Shodan Monitoring integration for TheHive)

README

        


  





  

  

  





ShoMon is a Shodan alert feeder for TheHive written in GoLang. With version 2.0, it is more powerful than ever!



# Functionalities

* Can be used as Webhook OR Stream listener

    * Webhook listener opens a restful API endpoint for Shodan to send alerts. This means you need to make this endpoint available to public net

    * Stream listener connects to Shodan and fetches/parses the alert stream

* Utilizes [shadowscatcher/shodan](https://github.com/shadowscatcher/shodan) (fantastic work) for Shodan interaction.

* Console logs are in JSON format and can be ingested by any other further log management tools

* CI/CD via Github Actions ensures that a proper Release with changelogs, artifacts, images on ghcr and dockerhub will be provided

* Provides a working [docker-compose file](docker-compose.yml) file for TheHive, dependencies

* Super fast and Super mini in size

* Complete code refactoring in v2.0 resulted in more modular, maintainable code

* Via conf file or environment variables alert specifics including tags, type, alert-template can be dynamically adjusted. See [config file](conf.yaml).

* Full banner can be included in Alert with direct link to Shodan Finding.

    ![Alert example](images/alert.png)

* IP is added to observables

    ![Observable example](images/observable.png)

# Usage

* Parameters should be provided via ```conf.yaml``` or environment variables. Please see [config file](conf.yaml) and [docker-compose file](docker-compose.yml)

* After conf or environment variables are set simply issue command: 

    `./shomon`

## Notes

* Alert reference is first 6 chars of md5("ip:port")

* Only 1 mod can be active at a time. Webhook and Stream listener can not be activated together.

# Setup & Compile Instructions

## Get latest compiled binary from releases

1. Check [Releases](https://github.com/KaanSK/shomon/releases/latest)  section.

## Compile from source code

1. Make sure that you have a working Golang workspace.

2. `go build .`

    * `go build -ldflags="-s -w" .` could be used to customize compilation and produce smaller binary.

## Using Public Container Registries

1. Thanks to new CI/CD integration, latest versions of built images are pushed to ghcr, DockerHub and can be utilized via:

    * `docker pull ghcr.io/kaansk/shomon`

    * `docker pull kaansk/shomon`

## Using [Dockerfile](Dockerfile)

1. Edit [config file](conf.yaml) or provide environment variables to commands bellow

2. `docker build -t shomon .`

3. `docker run -it shomon`

## Using [docker-compose file](docker-compose.yml)

1. Edit environment variables and configurations in [docker-compose file](docker-compose.yml)

2. `docker-compose run -d`

# Credits

* Logo Made via LogoMakr.com

* [shadowscatcher/shodan](https://github.com/shadowscatcher/shodan) 

* [Dockerfile Reference](https://www.cloudreach.com/en/resources/blog/cts-build-golang-dockerfiles/) 

* Release management with [GoReleaser](https://goreleaser.com)