shadowserver

README

Shadowserver-API-go

Simple Golang program to access Shadowserver API

This software is based on official API client and additional details can be found here

Description

The tool is developed and used by AM-CERT and include following capabilities:

• Query Shadowserver REST API
• Download Shadowserver reports in specified directory
• Schedule automated download of reports (see usage with systemd)

Usage

Download precompiled binaries from latest release for your architecture or clone the repository and compile it with the following command

GOOS=linux GOARCH=amd64 go build -o shadowserver-api-go-linux-amd64 github.com/AM-CERT/Shadowserver-API-go/cmd/shadowserver-api-go

Download configuration .env file and edit with your API credentials

curl -o .env https://raw.githubusercontent.com/AM-CERT/Shadowserver-API-go/main/.env

Run the binary to see the usage

./shadowserver-api-go-darwin-arm64 -h

Run without any param to check the credentials are valid

./shadowserver-api-go-darwin-arm64
[::] Jan  3 15:22:13.150 [I] [app:./shadowserver-api-go-darwin-arm64] starting
{
 "pong": "2024-01-03 11:22:13Z"
}

Download reports as specified in .env file, report directory must exist

./shadowserver-api-go-darwin-arm64 -reports

You can pass parameter to the API call:

./shadowserver-api-go-darwin-arm64 -method reports/query -param '{"query":{"geo":"AM", "type":["|sinkhole","|honeypot"],"date":"2023-02-14"},"limit":1}'

Usage with systemd

You can create a service to automatically download daily reports and keep an up-to-date directory structure with reports.

Create systemd service file:

# /etc/systemd/system/shadowserver-api-go.service
[Unit]
Description=Shadowserver-API-go service
After=network.target

[Service]
WorkingDirectory=/opt/Shadowserver-API-go
ExecStart=/opt/Shadowserver-API-go/shadowserver-api-go-linux-amd64 -reportsCron

[Install]
WantedBy=multi-user.target

Download configuration .env file and edit with your API credentials, download the binary for your OS/Arch

mkdir /opt/Shadowserver-API-go
cd /opt/Shadowserver-API-go
curl -o .env https://raw.githubusercontent.com/AM-CERT/Shadowserver-API-go/main/.env
wget https://github.com/AM-CERT/Shadowserver-API-go/releases/download/v0.1/shadowserver-api-go-linux-amd64

Reports directory must exist, create the directory mentioned in .env file:

mkdir /opt/Shadowserver-API-go/reports

Systemd command to reload, start, status and show logs:

systemctl daemon-reload
systemctl start shadowserver-api-go
systemctl status shadowserver-api-go
journalctl -f -u shadowserver-api-go

Using as a golang library

If you want to extend the capabilities of this tool by developing your own app, all functions are safe to import and use.

For example to make an API call:

// make a param struct
params := make(model.ShadowserverParam)

// load the query params
err = json.Unmarshal([]byte(`{"query":{"geo":"AM", "type":["|sinkhole","|honeypot"],"date":"2023-02-14"},"limit":1}`), &params)

// make the API call
data, _ := shadowserver.CallApi(method, params)

// print the result
shadowserver.PrintJson(data, true)

Need Help

Please check the issues first and open a new one if you can't find a solution.

License

• GNU GENERAL PUBLIC LICENSE. LICENSE or https://www.gnu.org/licenses/gpl-3.0.en.html#license-text

Documentation

Index

• Constants
• func CallApi(method string, param model.ShadowserverParam) ([]byte, error)
• func ComputeHmac(secret string, data []byte) string
• func DiskUsage(path string) (disk model.DiskStatus, err error)
• func DownloadReport(id string, path string) error
• func DownloadReports() ([]*model.ShadowserverReport, error)
• func FileExists(filename string) bool
• func GetReportList(param model.ShadowserverParam) ([]*model.ShadowserverReport, error)
• func PrintJson(data []byte, pretty bool)

Constants

const (
	B  = 1
	KB = 1024 * B
	MB = 1024 * KB
	GB = 1024 * MB
)

Functions

func CallApi

func CallApi(method string, param model.ShadowserverParam) ([]byte, error)

func ComputeHmac

func ComputeHmac(secret string, data []byte) string

ComputeHmac compute HMAC of data

func DiskUsage

func DiskUsage(path string) (disk model.DiskStatus, err error)

DiskUsage disk usage of path/disk

func DownloadReport

func DownloadReport(id string, path string) error

func DownloadReports

func DownloadReports() ([]*model.ShadowserverReport, error)

func FileExists

func FileExists(filename string) bool

FileExists check file exists

func GetReportList

func GetReportList(param model.ShadowserverParam) ([]*model.ShadowserverReport, error)

func PrintJson

func PrintJson(data []byte, pretty bool)

PrintJson print json string to stdout