{"id":16243339,"url":"https://github.com/kpetremann/claw-network","last_synced_at":"2026-02-19T23:37:10.248Z","repository":{"id":39862668,"uuid":"492761060","full_name":"kpetremann/claw-network","owner":"kpetremann","description":"Simulate network failures in a datacenter topology","archived":false,"fork":false,"pushed_at":"2025-04-19T16:57:18.000Z","size":1594,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-09-11T19:53:02.732Z","etag":null,"topics":["infra","infrastructure","maintenance","network","topology"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kpetremann.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":["kpetremann"],"patreon":null,"open_collective":null,"ko_fi":null,"tidelift":null,"community_bridge":null,"liberapay":null,"issuehunt":null,"otechie":null,"lfx_crowdfunding":null,"custom":null}},"created_at":"2022-05-16T09:09:45.000Z","updated_at":"2025-04-19T16:56:20.000Z","dependencies_parsed_at":"2025-04-19T17:51:11.342Z","dependency_job_id":null,"html_url":"https://github.com/kpetremann/claw-network","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/kpetremann/claw-network","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpetremann%2Fclaw-network","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpetremann%2Fclaw-network/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpetremann%2Fclaw-network/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpetremann%2Fclaw-network/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kpetremann","download_url":"https://codeload.github.com/kpetremann/claw-network/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kpetremann%2Fclaw-network/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29636614,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-19T22:32:43.237Z","status":"ssl_error","status_checked_at":"2026-02-19T22:32:38.330Z","response_time":117,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"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":["infra","infrastructure","maintenance","network","topology"],"created_at":"2024-10-10T14:14:39.668Z","updated_at":"2026-02-19T23:37:10.230Z","avatar_url":"https://github.com/kpetremann.png","language":"Go","funding_links":["https://github.com/sponsors/kpetremann"],"categories":[],"sub_categories":[],"readme":"[![status](https://img.shields.io/badge/status-in%20development-orange)](https://github.com/kpetremann/claw-network/)\n[![Go](https://img.shields.io/github/go-mod/go-version/kpetremann/claw-network)](https://github.com/kpetremann/claw-network/)\n[![CI](https://github.com/kpetremann/claw-network/actions/workflows/go.yml/badge.svg)](https://github.com/kpetremann/claw-network/actions/workflows/go.yml)\n[![GitHub](https://img.shields.io/github/license/kpetremann/claw-network)](https://github.com/kpetremann/claw-network/blob/main/LICENSE)\n\n# Overview\n\nClawNetwork is a tool to simulate a network and evaluate failures impacts on Top of Racks.\n\nIt has been specially crafted for Clos Matrix network. For now, cyclic graphs are not supported. Only trees are.\n\n```\nClawNetwork is in active development.\nThe main features are implemented, but endpoints, structures and functions may change.\n\nBut it is now usable and you are free to play with it :)\n```\n\n# Usecases\n\n## Operations\n\nThe main usecase it to evaluate if an operation on a device in your core network will impact a Top of Rack.\n\nConcerned operations can be: upgrade, reboot, risky maintenance etc...\n\n## Detect anomalies / SPOF\n\nClawNetwork can be leveraged to detect SPOF of any anomalies such as spine without downlinks.\n\n# Quickstart\n\n## From source\n\nSimply run ClawNetwork app using `go run .`\n\nAlternative: build the binary via `go build` and run it.\n\n## Using Docker compose\n\n### Default backend\n\nRun ClawNetwork with default backend (FileRepository):\n```shell\ndocker-compose -f compose/docker-compose.yml up -d\n```\n\nFileRepository stores the topologies in dedicated JSON files on the disk.\n\nBy default, this uses `examples/` directory provided in this repository.\n\n\u003e At the moment this is not customizable, but it will be very soon.\n\n### Run with the Backend of your choice\n\n```shell\ndocker-compose -f compose/docker-compose.yml -f \u003cbackend\u003e.yml up -d\n```\n\n#### RedisJSON\n\n\u003e recommended backend for production if you need to store topologies\n\nAt the moment, Redis JSON is the only alternative backend:\n```shell\ndocker-compose -f compose/docker-compose.yml -f redisjson.yml up -d\n```\n\nThis backend leverages [RedisJSON module](https://redis.io/docs/stack/json/) to store pure JSON to Redis. Persistence is enabled and forced at each changes (ADD/DELETE) by ClawNetwork.\n\n## Configuration\n\nConfiguration can be configured either via environment variables or YAML file (settings.yaml).\n\nList of parameters available (`varenv format` | `YAML format`):\n\n- `CLAW_LISTENADDRESS` | `ListenAddress`: ClawNetwork API listen address (default: `\"0.0.0.0\"`)\n- `CLAW_LISTENPORT` | `ListenPort`: ClawNetwork API listen port (default: `\"8080\"`)\n- `CLAW_TOPDEVICEROLE` | `TopDeviceRole`: Role of device at the top of the topology graph (default: `\"edge\"`)\n- `CLAW_BOTTOMDEVICEROLE` | `BottomDeviceRole`: Role of device at the Bottom of the topology graph (default: `\"tor\"`)\n- `CLAW_BACKEND` | `Backend`: Choose backend to store topologies (choices: `\"file\", \"redis\"`, default: `\"file\"`)\n- `CLAW_BACKENDS_FILE_PATH` | `Backends.Redis.Path`: Redis DB to use (default: `\"./topologies/\"`)\n- `CLAW_BACKENDS_REDIS_HOST` | `Backends.Redis.Host`: Redis server address (default: `\"localhost\"`)\n- `CLAW_BACKENDS_REDIS_PORT` | `Backends.Redis.Port`: Redis server port (default: `\"6379\"`)\n- `CLAW_BACKENDS_REDIS_PASSWORD` | `Backends.Redis.Password`: Redis password (default: `\"\"`)\n- `CLAW_BACKENDS_REDIS_DB` | `Backends.Redis.DB`: Redis DB to use (default: `0`)\n\n# Usage\n\n### Manage stored topologies\n\n- GET `/topology`: list stored topologies\n- GET `/topology/:topology_name`: get topology definition\n- POST `/topology/:topology_name`: create a new topology\n- DELETE `/topology/:topology_name`: delete a topology\n- GET `/topology/details`: list stored topologies with some stats\n- GET `/topology/:topology_name/details`: get topology stats\n\n### Simulation on a stored topology\n\n- GET `/topology/:topology_name/device/:device/down/impact`: run simulations on existing topology\n- POST `/topology/custom/device/:device/down/impact`: run simulations on topology provided in the request body\n\nIt will run a simulation on a stored topology.\n\nIf `:device` is set to `each`, it will simulate failure impact of each devices excluding Top of Racks.\n\n### Anomaly detection\n\n- GET `/topology/:topology_name/anomalies`: get topology anomalies\n\nIt list all anomalies in the topology graph.\n\n#### Link anomalies\n\nA node is not connected properly to the graph.\n\nFor example:\n- a ToR does not have any uplinks\n- a spine does not have any downlinks or any uplinks\n- an edge does not have any downlinks\n\nThis does not consider the status of the link, it only checks if there is a link.\n\n### Topology structure\n\nThe topology to provide looks like this in JSON:\n\n```json\n{\n  \"nodes\": [\n    {\n      \"hostname\": \"tor-01-01\",\n      \"role\": \"tor\",\n      \"status\": true,\n      \"layer\": 1\n    },\n    {\n      \"hostname\": \"fabric-1-01\",\n      \"role\": \"fabric\",\n      \"status\": true,\n      \"layer\": 2\n    }\n  ],\n  \"links\": [\n    {\n      \"south_node\": \"tor-01-01\",\n      \"north_node\": \"fabric-1-01\",\n      \"status\": true,\n      \"uid\": \"10.0.0.0-\u003e10.0.0.1\"\n    }\n  ]\n}\n```\n\n\u003e This structure is subject to change, as the API is not considered stable at the moment\n\n### Example\n\nTopology = 4 healthy fabric nodes + 4 healthy ToR\n\nSimulations:\n- first simulation considering first fabric node as down\n- second simulation considering second fabric node as down but with the first up\n- ...\n\n\n# Example usecase\n\nYou can query the following endpoint to simulate down impact of each devices. It get the tppology example from the `example/full_topology_with_issues.json`.\n\n```shell\n$ curl http://127.0.0.1:8080/topology/full_topology_with_issues/device/each/down/impact | jq\n{\n  \"scenarios_result\": {\n    \"edge-0\": {\n      \"impacts\": null,\n      \"parameters\": {\n        \"devices_down\": [\n          \"edge-0\"\n        ],\n        \"links_down\": null\n      }\n    },\n    \"edge-1\": {\n      \"impacts\": null,\n      \"parameters\": {\n        \"devices_down\": [\n          \"edge-1\"\n        ],\n        \"links_down\": null\n      }\n    },\n    \"fabric-1-01\": {\n      \"impacts\": [\n        \"tor-01-01\"\n      ],\n      \"parameters\": {\n        \"devices_down\": [\n          \"fabric-1-01\"\n        ],\n        \"links_down\": null\n      }\n    },\n    ...,\n    \"compute_time\": \"89 ms\"\n}\n```\n\nAs you can see, `tor-01-01` would be down if we shut `fabric-1-01`.\n\nThe topology defined in `example/full_topology_with_issues.json`, also specifies some devices as down. Here all the fabric of pod 01 has been set to down except for `fabric-1-01`. This is why if there is a failure on this device, it will impact `tor-01-01` as this ToR only had one healthy uplink.\n\nNote: more advanced examples will be provided soon, with more complex scenarios.\n\n# Integrations\n\nBelow some ideas of possible integrations:\n\n- the client push the topology with the simulation request. The topology is not stored.\n```\n+-------------------------+\n|  Observability metrics  |\n|   example: Prometheus   |\n+-------------------------+\n             ^\n             |\n             | get metrics\n             |\n             |\n             |\n +-----------------------+\n |                       |           get impact\n |        Client         |        on custom topology        +---------------+\n |   =\u003e convert metrics  |---------------------------------\u003e|  ClawNetwork  |\n |      to topology      |                                  +---------------+\n +-----------------------+\n```\n\n- the client provides the topologies and they are stored\n```\n+-------------------------+\n|  Observability metrics  |\n|   example: Prometheus   |\n+-------------------------+\n             ^\n             |\n             | get metrics\n             |\n             |\n             |\n +-----------------------+\n |        Client         |       push topology      +---------------+      save topology       +-------------------------+\n |   =\u003e convert metrics  |-------------------------\u003e|  ClawNetwork  |\u003c------------------------\u003e| Storage (FS, redis,...) |\n |      to topology      |        get impact        +---------------+       get topology       +-------------------------+\n +-----------------------+\n```\n\n- dedicated topology provider\n```\n                                                 +---------------------+\n+-------------------------+                      |  Topology provider  |\n|  Observability metrics  | \u003c------------------- | =\u003e convert metrics  |\n+-------------------------+                      |    to topology      |\n                                                 +---------------------+\n                                                            |\n                                                            |\n                                                            | push topology\n                                                            |\n                                                            |\n                                                            |\n                                                            v\n +-----------------------+        get impact        +---------------+      save topology       +-------------------------+\n |        Client         |-------------------------\u003e|  ClawNetwork  |\u003c------------------------\u003e| Storage (FS, redis,...) |\n +-----------------------+                          +---------------+       get topology       +-------------------------+\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpetremann%2Fclaw-network","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkpetremann%2Fclaw-network","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkpetremann%2Fclaw-network/lists"}