Skip to content

Latest commit

 

History

History
280 lines (197 loc) · 12.3 KB

README.md

File metadata and controls

280 lines (197 loc) · 12.3 KB
Raw

Contributors Forks Stargazers Issues GNU GPL V3 License LinkedIn


Logo

Tommyknocker

Tommyknocker is a platform designed to allow for continuous, automated testing and validation of various security controls. Each time you make a change to your environment or security controls, you run the risk of impacting the proper functioning or reporting of other controls in the environment. For example, a change in firewall policy on an external firewall may lead to exposure of internal resources that were believed to be blocked by another internal firewall. Additionally, if a malicious threat actor, or insider threat actor manages to disable a security control, you may not realize it until the next time someone is investigating that control for some reason. Tommyknocker gives you the ability to build up the equivalent of a regression test suite focusing on ensuring that your security controls remain active and effective over time. · Report Bug · Request Feature

Table of Contents
  1. About The Project
  2. Getting Started
  3. Usage
  4. Roadmap
  5. Contributing
  6. License
  7. Contact
  8. Acknowledgments

About The Project

Tommyknocker started from the idea to bring the long understood benefits of regression testing methods to the realm of infosec. In a traditional regression test, the fix for each reported bug or issue in a software product is accompanied by a small test that validates that the same issue does not occur again in the future. With Tommyknocker, each security control put in place can be accompanied by a test case, which can ensure that future changes do not impact the functioning and/or reporting of that control.

Most organizations will often avoid doing testing of security controls unless it is absolutely necessary for an event such as an audit or yearly review. This can easily lead to the organization having a false sense of security, as controls may be inactive or improperly configured for months or even years before the next event that requires a test. By automating the process of testing these controls, organizations can not only ensure that controls remain functional, they can reduce the manual effort required to produce evidence of controls for auditing purposes significantly!

(back to top)

Built With

  • Python
  • Angular
  • Clarity

(back to top)

Getting Started

The easiest and fastest way to kick the tires is to run the all-in-one docker container. This container runs the controller, UI, and a single knocker, so that you can try out the service. The knocker service requires access to a Docker runtime, so you will need to forward your local docker socket as a volume.

docker run -p 80:4200 -v /var/run/docker.sock:/var/run/docker.sock -d ghcr.io/loredous/tommyknocker-aio:main

Once the container image downloads and executes, you should be able to navigate to http://localhost in a browser, and be presented with the Tommyknocker WebUI

Logo

Prerequisites

All Python back-end dependencies are managed using Pipenv, and UI dependencies are managed with npm

  • Pipenv 
    pipenv install --dev
  • npm 
    npm install npm@latest -g

Installation

There are multiple options for installing and running the Tommyknocker service.

All-in-one Docker Container

The easiest and fastest way to kick the tires is to run the all-in-one docker container. This container runs the controller, UI, and a single knocker, so that you can try out the service. The knocker service requires access to a Docker runtime, so you will need to forward your local docker socket as a volume.

docker run -p 80:4200 -v /var/run/docker.sock:/var/run/docker.sock -d ghcr.io/loredous/tommyknocker-aio:main

Once the container image downloads and executes, you should be able to navigate to http://localhost in a browser, and be presented with the Tommyknocker WebUI

Separate Controller and Knocker containers

To deploy the Controller container, just run the docker container

docker run -p 80:4200 -d ghcr.io/loredous/tommyknocker-controller:main

Once the controller is configured for one or more knockers, you can execute the knocker docker containers with the appropriate ID values

docker run -p 80:4200 -v /var/run/docker.sock:/var/run/docker.sock -d ghcr.io/loredous/tommyknocker-knocker:main -c <controller_address> -p <controller_port> -I <knocker_ID_value>

Building Containers Locally

To build the docker container images locally, clone the git repository, and run the following commands from the root of the repository:

All-in-one

docker build . --target all-in-one -t tommyknocker-aio:local

Controller

docker build . --target controller -t tommyknocker-controller:local

Knocker

docker build . --target all-in-one -t tommyknocker-knocker:local

(back to top)

Usage

The Tommyknocker service is mainly configured through the WebUI, using the items in the "Test Management" and "Infrastructure" sections. The general workflow for starting out without any pre-seeded data would be:

  1. Deploy the Controller service as instructed in the installation section.
  2. Create a new Knocker configuration and note the ID value.
  3. Deploy a Knocker as instructed in the installation section, with the ID you just created. Knockers should be deployed to a docker runtime from which the knocks will be executed.
  4. Ensure that the knocker is properly checking in and communicating.
  5. Configure any desired Monitors through the webUI. Monitors are services that can be checked after a knock is complete to confirm that any expected alerting or logging is actually present.
  6. Create a Runner configuration for your first knock. The runner configuration controls what docker image is used to actually execute a knock.
  7. Create any desired Response configurations. A response configuration contains the actual data that is expected to be seen in a monitor after a knock occurs.
  8. Create an appropriate Knock and Result configuration. A knock specifies the commands to be run on the runner for a test. A Result is an expected output from the knock command itself (text output, exit code, etc).
  9. Create a Test Configuration that uses the Knock and Response you configured previously.
  10. On the Test Runs page, select "Add Test Run", and add a test run with the configuration you created, running on the knocker you deployed.
  11. You should be able to watch the test progress as it knocks, and checks for the appropriate responses.

(back to top)

Roadmap

  • [✅] Basic Clarity WebUI
  • [✅] Dockerized deployment
  • Ability to organize tests and test-suites by tags (Control IDs, CVE numbers, etc)

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

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

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

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

(back to top)

License

Distributed under the GNU GPLv3 License. See LICENSE.txt for more information.

(back to top)

Contact

Jeremy Banker - [email protected]

Project Link: https://github.com/loredous/tommyknocker

(back to top)

Acknowledgments

Coming Soon!

(back to top)