{"id":30450225,"url":"https://github.com/deflect-ca/baskerville_client","last_synced_at":"2026-02-12T10:33:02.703Z","repository":{"id":45934304,"uuid":"372897397","full_name":"deflect-ca/baskerville_client","owner":"deflect-ca","description":"Baskerville client","archived":false,"fork":false,"pushed_at":"2022-04-22T17:05:22.000Z","size":86,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":4,"default_branch":"main","last_synced_at":"2024-05-01T15:01:42.355Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/deflect-ca.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-06-01T16:35:06.000Z","updated_at":"2024-04-05T18:57:45.000Z","dependencies_parsed_at":"2022-09-23T17:22:32.752Z","dependency_job_id":null,"html_url":"https://github.com/deflect-ca/baskerville_client","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/deflect-ca/baskerville_client","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deflect-ca%2Fbaskerville_client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deflect-ca%2Fbaskerville_client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deflect-ca%2Fbaskerville_client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deflect-ca%2Fbaskerville_client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/deflect-ca","download_url":"https://codeload.github.com/deflect-ca/baskerville_client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/deflect-ca%2Fbaskerville_client/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":271749048,"owners_count":24814115,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-23T02:00:09.327Z","response_time":69,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-08-23T13:25:56.547Z","updated_at":"2026-02-12T10:33:02.690Z","avatar_url":"https://github.com/deflect-ca.png","language":"Dockerfile","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\n## What is Baskerville?\n\nManual identification and mitigation of (DDoS) attacks on websites is a difficult and time-consuming task with many challenges. This is why Baskerville was created, to identify the attacks directed to Deflect protected \nwebsites as they happen and give the infrastructure the time to respond properly. Baskerville is an analytics engine that leverages Machine Learning to distinguish between normal and abnormal web traffic behavior. \n\nIn short, Baskerville is a Layer 7(application layer) DDoS attack mitigation tool.\n\n## What is Baskerville client?\n\nBaskerville client is a client module which:\n* Processes nginx web server logs and calculates statistical features.\n* Sends features to a clearing house instance of Baskerville.\n* Receives predictions from a clearing house for every IP.\n* Issues challenge commands for every malicious IP in a separate Kafka topic.\n* Monitors attacks in Grafana dashboards.\n\n# System requirements\n* Linux server with Docker already installed.\n* A minimum of 8GB of RAM is suggested.\n* Allow TCP network traffic on port `29092` for the Kafka connection from the clearing house to the client.\n* Allow TCP network traffic on port `3000` for access to the Grafana dashboard.\n\n# Installation\nDownload the Baskerville client software into the current working directory and change directories:\n```commandline\ngit clone https://github.com/deflect-ca/baskerville_client.git \u0026\u0026 cd baskerville_client\n```\n\n## Configuration\n\n* Ensure the following directories exist:\n```commandline\nmkdir -p /var/log/nginx \u0026\u0026 mkdir -p /var/log/banjax-next\n```\n\n* Create the `.env` file:\n```commandline\ncp dot_env.sh .env\n```\n* Make the following modifications to the `.env` file:\n    * Set `CLEARING_HOUSE_KAFKA` variable to your Baskerville clearing house URL.\n    * Set `KAFKA_HOST` variable to your server's IP address.\n    * Set provided passwords `KAFKA_KEYSTORE_PASSWORD` and `KAFKA_TRUSTSTORE_PASSWORD`.\n\n* Add TLS keys provided by clearing house into the `./clearing_house_connection` directory. \n```commandline\n./clearing_house_connection/caroot.pem\n./clearing_house_connection/certificate.pem\n./clearing_house_connection/key.pem\n```\n\n* Add local Kafka keys provided by clearing house into the `./kafka_local` directory:\n```commandline\n./conf/kafka_local/kafka.keystore.jks\n./conf/kafka_local/kafka.truststore.jks\n```\n\n* Create your client id and set it in `./conf/preprocessing.yaml` and `./conf/postprocessing.yaml`:\n```yaml\nengine:\n  id_client: '...'\n```\n\n* Provide clearing house with your `client_id` and your kafka external URL:\n```yaml\nyour_ip:29092\n```\n\n* Change your postgres password in `.env`:\n```commandline\nBASKERVILLE_POSTGRES_PASSWORD=changeme\n```\n\n* Change your postgres password in `containers/grafana/datasources/postgresql.yaml`:\n```yaml\ndatasources:\n  secureJsonData:\n    password: ...\n```\n\n* Change your Grafana `admin` password in `containers/grafana/Dockerfile`:\n```commandline\nENV GF_SECURITY_ADMIN_PASSWORD ...\n```\n# Post installation\n\n## Run Baskerville client\n* To launch the software, run the following command:\n```\ndocker-compose up -d\n```\n\n* Open the Grafana dashboard at `localhost:3000` and log in with your Grafana admin password. \n\n* Open dashboards `baskerville/Attack` and `baskerville/TrafficLight`.\n\n## Troubleshooting\n### Containers fail to start\nIn case the `baskerville_preprocessing` and `baskerville_postprocessing` containers fail to start because the `baskerville` database does not exist:\n```bash\ndocker-compose exec postgres bash\npsql\nCREATE DATABASE baskerville;\n\\q\nexit\n\ndocker-compose restart baskerville_preprocessing baskerville_postprocessing\n```\n\n### Ensure kafka is healthy \nTo verify kafka is receiving logs:\n- First open your browser at `http://localhost/test` (or any other similar URL) and refresh a few times\n- Verify that your requests were written to the right file:\n  ```bash\n  tail -f /var/log/banjax-next/nginx-logstash-format.log\n  ```\n- Check your filebeat and logstash logs for any errors if necessary:\n```bash\ndocker-compose logs -f logstash\ndocker-compose logs -f filebeat \n```\n- Then log in to the kafka service and consume a few messages from the logs topic, e.g. `deflect.logs`:\n```bash\ndocker-compose exec kafka bash\n# this will provide the message count, e.g. partition 0 has 6131 messages\n# so not zero message count means we are receiving correctly\n/opt/bitnami/kafka/bin/kafka-run-class.sh kafka.tools.GetOffsetShell --broker-list localhost:9092 --topic deflect.logs\n\u003e\u003e\u003e deflect.logs:0:6131\n\n# the following will consume / display a few messages, just to make sure all is well\n/opt/bitnami/kafka/bin/kafka-console-consumer.sh --bootstrap-server localhost:9092 --topic deflect.logs --offset 6131 --partition 0\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeflect-ca%2Fbaskerville_client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdeflect-ca%2Fbaskerville_client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdeflect-ca%2Fbaskerville_client/lists"}