Koala Shield 🐨 🛡

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
   • lookup
   • block
   • un-block
   • ipsets
4. Tests
5. Contributing
6. License
7. Contact

About The Project

Koala Shield is a small package and CLI tool written in Go to help investigate IP address/ASNs and manage block lists in AWS WAF Classic.

Koala Shield makes it easy to track any IP address to their ASN owner and, if the ASN owner appears malicious, quickly create a AWS WAF Classic block rule to guard against widespread malicious behavior.

If a malicious actor is using a less-than scrupulous cloud provider to DDoS your application Koala Shield can be used to temporarily block the cloud provider and give you time to find a more permanent solution.

Be careful when blocking an entire ASN! An ASN can encompass a wide range of services and networks so be sure to triple confirm before enabling the block. Koala Shield makes it easy to rollback a block if needed.

Getting Started

Prerequisites

Koala Shield requires Go 1.15 or higher. As a prerequisite please download and install Go and make sure Go compiled binaries are included in your $PATH (e.g. export PATH=$GOPATH/bin:$PATH)

Installation

1. Install the binary

   go get github.com/koala-labs/koala-shield

2. Set your AWS credentials and make sure to export your desired AWS region in the AWS config file.

Usage

Koala Shield has 4 core commands: lookup, block, un-block, and ipsets:

lookup

Lookup information about IP addresses and/or ASN numbers (powered by BPGView)

Example:

koala-shield lookup 20473
koala-shield lookup 8.6.8.0

block

Block all the prefixes owned by the specified ASN using an AWS WAF Classic IP list.

Example:

koala-shield block 20473

un-block

Un-block an ASN by removing their IP Set from the AWS WAF Classic IP Rules.

Example:

koala-shield un-block 20473

ipsets

List all IP sets registered in AWS WAF Classic.

Example:

koala-shield ipsets

Tests

Koala Shield has a full unit-test suite.

Use the following command to run the tests and output function-level code coverage

go test ./... -coverprofile coverage.txt && go tool cover -func coverage.txt

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated.

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Run the test suite (go test ./...)
4. Commit your Changes (git commit -m 'Add some AmazingFeature')
5. Push to the Branch (git push origin feature/AmazingFeature)
6. Open a Pull Request

License

Distributed under the Apache License, Version 2.0. See LICENSE for more information.

Contact

Koala Labs - @koala_labs - engineering@koala.io