sebel

README

sebel

sebel is a Go package that provides functionality for checking SSL/TLS certificates against malicious connections, by identifying and blacklisting certificates used by botnet command and control (C&C) servers.

Usage

Setting up Sebel instance:

import "github.com/teler-sh/sebel"

// ...

s := sebel.New(Options{/* ... */})

[!NOTE] The Options parameter is optional. Currently, the only supported option is disabling the SSL blacklist. See TODO.

Examples

Next, set the transport for the HTTP client you are using:

// initialize Sebel (fetch SSLBL data)
s := sebel.New()

client := &http.Client{
    Transport: s.RoundTripper(http.DefaultTransport),
}

// now, you can use [client.Do], [client.Get], etc. to create requests.

resp, err := client.Get("https://c2.host")
if err != nil && sebel.IsBlacklist(err) {
    // certificate blacklisted
    panic(err)
}
defer resp.Body.Close()

Alternatively, for seamless integration without configuring a new client, replace your current default HTTP client with Sebel's RoundTripper:

http.DefaultClient.Transport = sebel.New().RoundTripper(http.DefaultTransport)

You can also check the certificate later using Sebel's CheckTLS.

r, err := http.Get("https://c2.host")
if err != nil {
	panic(err)
}
defer r.Body.Close()

s := sebel.New()

_, err = s.CheckTLS(r.TLS)
if err != nil && sebel.IsBlacklist(err) {
	// certificate blacklisted
	panic(err)
}

These examples demonstrate various ways to set up Sebel and integrate it with HTTP clients for SSL/TLS certificate checks.

TODO

• Caching SSLBL data under user-specific cache directory.
• Add io.Writer option.
• Add CheckIP method. Not planned, instead:
• Add CheckHost method.

Status

[!CAUTION] Sebel has NOT reached 1.0 yet. Therefore, this library is currently not supported and does not offer a stable API; use at your own risk.

There are no guarantees of stability for the APIs in this library, and while they are not expected to change dramatically. API tweaks and bug fixes may occur.

License

sebel is released by @dwisiswant0 under the Apache 2.0 license. See LICENSE.

The data used in this project are © by abuse.ch under CC0.

Documentation

Overview

Package sebel provides functionality for checking SSL/TLS certificates against a malicious connections, by identifying and blacklisting certificates used by botnet command and control (C&C) servers.

Index

• Variables
• func IsBlacklist(err error) bool
• type Options
• type Sebel
  • func New(opt ...Options) *Sebel
  • func (s *Sebel) CheckTLS(connState *tls.ConnectionState) (*sslbl.Record, error)
  • func (s *Sebel) RoundTripper(rt http.RoundTripper) http.RoundTripper

Examples

• New
• Sebel.CheckTLS
• Sebel.RoundTripper

Variables

var (
	ErrSSLBlacklist = errors.New("certificate blacklisted")
	ErrNoSSLBLData  = errors.New("no SSLBL data")
)

Functions

func IsBlacklist

func IsBlacklist(err error) bool

IsBlacklist checks if the given error is an ErrSSLBlacklist.

Types

type Options

type Options struct {
	// DisableSSLBlacklist, when set to true, disables SSL/TLS certificate
	// blacklist checks.
	DisableSSLBlacklist bool
}

Options holds configuration settings for the Sebel package.

type Sebel

type Sebel struct {
	// contains filtered or unexported fields
}

Sebel holds information and Options.

func New

func New(opt ...Options) *Sebel

New creates a new instance of Sebel with the provided options.

Example

package main

import (
	"net/http"

	"github.com/teler-sh/sebel"
)

func main() {
	client := &http.Client{
		Transport: sebel.New().RoundTripper(http.DefaultTransport),
	}

	resp, err := client.Get("https://c2.host")
	if err != nil && sebel.IsBlacklist(err) {
		// certificate blacklisted
		panic(err)
	}
	defer resp.Body.Close()

	println("OK")
}

func (*Sebel) CheckTLS

func (s *Sebel) CheckTLS(connState *tls.ConnectionState) (*sslbl.Record, error)

CheckTLS checks the TLS connection against the SSLBL (SSL Blacklist) and returns the SSLBL record.

It returns ErrSSLBlacklist error if the certificate is blacklisted.

Example

package main

import (
	"net/http"

	"github.com/teler-sh/sebel"
)

func main() {
	r, err := http.Get("https://c2.host")
	if err != nil {
		panic(err)
	}
	defer r.Body.Close()

	s := sebel.New()

	_, err = s.CheckTLS(r.TLS)
	if err != nil && sebel.IsBlacklist(err) {
		// certificate blacklisted
		panic(err)
	}
}

func (*Sebel) RoundTripper

func (s *Sebel) RoundTripper(rt http.RoundTripper) http.RoundTripper

RoundTripper creates a new RoundTripper using the provided http.RoundTripper and Sebel instance.

Example

To seamlessly integrate it without need to configure a new client, you can simply replace your current http.DefaultClient with sebel's RoundTripper.

package main

import (
	"net/http"

	"github.com/teler-sh/sebel"
)

func main() {
	http.DefaultClient.Transport = sebel.New().RoundTripper(http.DefaultTransport)
}