turtle

README

🐢 Turtle is a toolkit for simulating and validating application layer denial-of-service attacks in both live and unit testing environments.

🚨 Disclaimer

Important: The use of this program for attacking targets without prior mutual consent is illegal. It is the end user's responsibility to comply with all applicable local, state, and federal laws. The developers assume no liability and are not responsible for any misuse or damage caused by this program.

🎯 Why Use Turtle?

Exposing an application to the public internet is fraught with risks due to various types of denial-of-service attacks, such as:

• slowloris
• low and slow attack
• R.U.D.Y
• ... and many more

While some applications may have well-configured settings that render them invulnerable to these attacks, others, such as those built with popular languages like Golang, might be vulnerable by default. Turtle provides an easy way to validate your application against these common threats to identify risks.

Furthermore, an application that is secure today may become vulnerable due to future changes. Therefore, integrating these attack simulations into your regular validation process is crucial.

🛠 Features

Turtle provides:

• A Command-Line Interface (CLI) for validating real endpoints
• A Golang library for easy integration into unit/integration tests

Supported Scenarios

Turtle current supports the following scenarios:

• slowloris
• slow body read

🚀 Getting Started

Turtle CLI

You can install the CLI tool via:

go install github.com/b4fun/turtle/cmd/turtle@latest

Or download a release binary from the GitHub Release page.

Using Turtle CLI

The turtle CLI embeds supported scenarios as sub-commands. A common way to invoke a scenario test:

$ turtle <scenario-name> <target-url>

Further details can be obtained by viewing the command's help message:

$ turtle -h
# Scenario specified help
$ turtle slowloris -h

Turtle Golang Library

For the Golang library, documentation can be found on GoDoc.

📜 LICENSE

Turtle is distributed under the [MIT license][/LICENSE]

Documentation

Index

• Constants
• func ErrorFromEvent(e Event) (err error, ok bool)
• func WorkerIdFromEvent(e Event) (id int, ok bool)
• type AsyncEventHandler
  • func NewAsyncEventHandler(h EventHandler, cap int) *AsyncEventHandler
  • func (f *AsyncEventHandler) Close() error
  • func (f *AsyncEventHandler) HandleEvent(event Event)
• type Event
  • func NewEvent(eventName string, settings ...EventSettings) Event
• type EventHandleFunc
  • func (f EventHandleFunc) HandleEvent(event Event)
• type EventHandler
• type EventSettings
  • func WithEventError(err error) EventSettings
  • func WithEventWorkerId(workerId int) EventSettings
• type SlowBodyReadRequest
  • func (s *SlowBodyReadRequest) AfterApply() error
  • func (s *SlowBodyReadRequest) Run(ctx context.Context) error
• type Slowloris
  • func (s *Slowloris) AfterApply() error
  • func (s *Slowloris) Run(ctx context.Context) error
• type Target

Examples

• SlowBodyReadRequest
• Slowloris

Constants

const (
	EventTCPDial   = "tcp/dial"
	EventTCPClosed = "tcp/closed"

	EventWorkerError = "worker/error"
	EventWorkerPanic = "worker/panic"
)

Functions

func ErrorFromEvent

func ErrorFromEvent(e Event) (err error, ok bool)

func WorkerIdFromEvent

func WorkerIdFromEvent(e Event) (id int, ok bool)

Types

type AsyncEventHandler

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

func NewAsyncEventHandler

func NewAsyncEventHandler(h EventHandler, cap int) *AsyncEventHandler

func (*AsyncEventHandler) Close

func (f *AsyncEventHandler) Close() error

func (*AsyncEventHandler) HandleEvent

func (f *AsyncEventHandler) HandleEvent(event Event)

type Event

type Event struct {
	// Name - event name
	Name string
	// At - event time
	At time.Time
	// Attrs - optional event attributes
	Attrs map[string]any
}

Event represents an event.

func NewEvent

func NewEvent(eventName string, settings ...EventSettings) Event

NewEvent creates a new event.

type EventHandleFunc

type EventHandleFunc func(event Event)

func (EventHandleFunc) HandleEvent

func (f EventHandleFunc) HandleEvent(event Event)

type EventHandler

type EventHandler interface {
	HandleEvent(event Event)
}

EventHandler handles events.

var NilEventHandler EventHandler = EventHandleFunc(func(event Event) {})

NilEventHandler is an event handler that does nothing.

type EventSettings

type EventSettings func(e *Event)

EventSettings configures an event.

func WithEventError

func WithEventError(err error) EventSettings

WithEventError binds the error of the event attrs.

func WithEventWorkerId

func WithEventWorkerId(workerId int) EventSettings

WithEventWorkerId binds the worker id of the event attrs.

type SlowBodyReadRequest

type SlowBodyReadRequest struct {
	Target Target `embed:""`

	// Method - the HTTP method to use, one of POST / PUT. Defaults to POST.
	Method string `name:"http-method" help:"the HTTP method to use, one of POST / PUT. Defaults to POST."`

	// BodyReadTimeout - the timeout for reading the request body. Defaults to hang forever.
	BodyReadTimeout time.Duration `name:"http-read-timeout" help:"the timeout for reading the request body. Defaults to hang forever."`
	// contains filtered or unexported fields
}

SlowBodyReadRequest provides the configurations for simulating slow request body reading attack.

Example

u, err := url.Parse("http://127.0.0.1:8080")
if err != nil {
	panic(err)
}

s := SlowBodyReadRequest{
	Target: Target{
		Url: *u,
	},
	Method:          http.MethodPost,
	BodyReadTimeout: 180 * time.Second,
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

_ = s.Run(ctx)

func (*SlowBodyReadRequest) AfterApply

func (s *SlowBodyReadRequest) AfterApply() error

func (*SlowBodyReadRequest) Run

func (s *SlowBodyReadRequest) Run(ctx context.Context) error

type Slowloris

type Slowloris struct {
	Target Target `embed:""`

	// Method - the HTTP method to use. Defaults to GET
	Method string `name:"http-method" help:"the HTTP method to use. Defaults to GET"`

	// UserAgents - list of user agents to use.
	// If more than one is provided, a random one will be selected.
	// If none is provided, a default one will be used.
	UserAgents []string `` /* 167-byte string literal not displayed */

	// SendGibberish - whether to send gibberish data in the request header.
	SendGibberish bool `name:"http-send-gibberish" help:"whether to send gibberish data in the request header"`

	// GibberishInterval - the random interval to send gibberish data in the request header. Defaults to 3s.
	GibberishInterval time.Duration `name:"http-gibberish-interval" help:"the random interval to send gibberish data in the request header"`

	// WriteTimeout - the timeout for writing the request header. Defaults to 10s.
	WriteTimeout time.Duration `name:"http-write-timeout" help:"the timeout for writing the request header. Defaults to 10s."`
	// contains filtered or unexported fields
}

Slowloris provides the configurations for running slowloris attack.

Example

u, err := url.Parse("http://127.0.0.1:8080")
if err != nil {
	panic(err)
}

s := Slowloris{
	Target: Target{
		Url: *u,
	},
	SendGibberish:     true,
	GibberishInterval: 5 * time.Millisecond,
	UserAgents: []string{
		"turtle/0.0.1",
		"turtle/0.0.1 - slowloris",
	},
}

ctx, cancel := context.WithCancel(context.Background())
defer cancel()

_ = s.Run(ctx)

func (*Slowloris) AfterApply

func (s *Slowloris) AfterApply() error

func (*Slowloris) Run

func (s *Slowloris) Run(ctx context.Context) error

type Target

type Target struct {
	// Url - the url of the target.
	Url url.URL `arg:"" name:"target-url" help:"the url of the target"`
	// Duration - the duration of the attack. Defaults to 30s.
	Duration time.Duration `name:"target-duration" help:"the duration of the attack. Defaults to 30s"`
	// Connections - the number of connections to be made. Defaults to 100.
	Connections int `name:"target-connections" help:"the number of connections to be made. Defaults to 100"`

	// EventHandler - optional event handler to use.
	EventHandler EventHandler `kong:"-"`
}

Target provides target configuration.