{"id":18538652,"url":"https://github.com/katharaframework/kathara-lab-checker","last_synced_at":"2025-10-30T06:41:40.871Z","repository":{"id":223309284,"uuid":"738624550","full_name":"KatharaFramework/kathara-lab-checker","owner":"KatharaFramework","description":"Tool to automatically check Kathará network scenarios based on a configuration file.","archived":false,"fork":false,"pushed_at":"2025-03-31T14:31:24.000Z","size":1366,"stargazers_count":3,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-31T14:59:16.533Z","etag":null,"topics":["kathara","kathara-lab","network-emulation","teaching","teaching-tool","testing"],"latest_commit_sha":null,"homepage":"https://www.kathara.org/","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/KatharaFramework.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"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}},"created_at":"2024-01-03T16:54:20.000Z","updated_at":"2025-03-31T14:24:57.000Z","dependencies_parsed_at":"2024-02-19T15:47:45.575Z","dependency_job_id":"0909623f-bdd1-4772-83cb-3e3da5b0f86b","html_url":"https://github.com/KatharaFramework/kathara-lab-checker","commit_stats":null,"previous_names":["tcaiazzi/kathara-lab-checker","katharaframework/kathara-lab-checker"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatharaFramework%2Fkathara-lab-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatharaFramework%2Fkathara-lab-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatharaFramework%2Fkathara-lab-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/KatharaFramework%2Fkathara-lab-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/KatharaFramework","download_url":"https://codeload.github.com/KatharaFramework/kathara-lab-checker/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248078433,"owners_count":21044103,"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","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":["kathara","kathara-lab","network-emulation","teaching","teaching-tool","testing"],"created_at":"2024-11-06T19:44:38.007Z","updated_at":"2025-10-30T06:41:40.809Z","avatar_url":"https://github.com/KatharaFramework.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Kathará Lab Checker\n\n## What is it?\n\nKathará Lab Checker is a tool to automatically check Kathará network scenarios. The tool leverages on a configuration\nfile (no coding) to specify the tests to run on the scenarios and then outputs files containing the results of the\ntests.\n\nThe tool is very effective for automatically correct student homeworks, exams and network scenario configurations.\n\n## Installation\n\n```bash\npython3 -m pip install kathara-lab-checker\n```\n\nThe Python version MUST be `\u003e=3.11`.\n\n## How does it work?\n\nThe Kathará Lab Checker takes in input a configuration file specifying the tests to perform and the expected values.\nTo run the tool you only need to run the `main.py` passing the desired configuration file.\n\n```bash\npython3 -m kathara_lab_checker --config \u003cpath-to-the-configuration-file\u003e --labs \u003cpath-to-the-labs-directory\u003e\n```\n\nAt this point, the tool parses the provided configuration file and executes the tests. For each network scenario the\ntool creates a report file in the network scenario directory.\n\nThe file is composed of three sheets:\n\n1. `Summary`: Contains a summary of the results.\n2. `All`: Contains the results for each test.\n3. `Failed`: Contains only the results of failed tests.\n\nBy default, reports are generated as a set of CSV files; however, you can choose to generate a consolidated Excel\nspreadsheet or disable report generation entirely using the `--report-type` flag.\n\nAfter all the network scenarios are tested, a combined report (either `results.xlsx` or `results.csv`, as selected) is\nplaced in the network scenarios\ndirectory containing all the results for each network scenario, including the reasons for failed tests.\n\n## Running the example\n\nThe repository already provide a complete example with the results of the tests.\n\n- Check the test configuration by inspecting: [configuration_palabra.json](examples/palabra/correction.json).\n- Check the network topology and requisites: [palabra.pdf](examples/palabra/palabra.pdf)\n- Check final results summary: [results.xlsx](examples/palabra/results.xlsx)\n\nYou can re-run the example by typing the following command in the root directory of the project:\n\n```bash\npython3 -m kathara_lab_checker --config examples/palabra/correction.json --no-cache --labs examples/palabra/labs\n```\n\nThe `--no-cache` flag force to repeat already executed tests.\n\n## Running on Docker\n\nTo build a Docker image containing both `Kathará` and the `kathara-lab-checker` tool, follow\nthe [guide](scripts/docker).\n\n## How to configure?\n\nThe `structure` file can be written in either **JSON** or **YAML** format. With **YAML**, you may inline your Kathará\nlab structure under `lab_inline`. If you specify it like in the following, the tool uses it as your `structure` file\nautomatically.\n\n```yaml\nlab_inline: |\n  router1[0]=\"net12\"\n  router2[0]=\"net12\"\n  ...\n```\n\nIn the following you will find the possible values for the configuration file.\n\n```\n{\n  \"labs_path\": \"\u003cpath\u003e\", # path to the folder containing the network scenarios\n  \"convergence_time\": \"\u003csec\u003e\", # second to wait for routing convergence in the network scenarios\n  \"structure\": \"\u003cpath\u003e\", # path to a lab_conf file specifying the correct lab schema\n  \"default_image\": \"\u003cimage_name\u003e\", # Kathara image to use as default image in the network scenarios\n  \"test\": {\n    \"requiring_startup\": [\n    \"\u003cdevice_name\u003e\" # Check the presence of startup files for the specified device\n    ], \n    \"ip_mapping\": {\n      \"\u003cdevice_name\u003e\": {\n        \"\u003cinterface_name\u003e\u003e\": \"\u003cip/netmask\u003e\" # Check that the ip/netmask is configured on the interface of the device\n        \"\u003cinterface_num\u003e\u003e\": \"\u003cip/netmask\u003e\" # Check that the ip/netmask is configured on the interface eth# of the device\n      },\n    },\n    \"daemons\": {\n      \"\u003cdevice_name\u003e\": [\n        \"\u003cdaemon_name\u003e\", # check that the daemon is running on the device.\u003e\",\n        \"!\u003cdaemon_name\u003e, # check that the daemon is not running on the device.\u003e\"\n      ]\n    },\n    # checks that the expected routing table is equal to the the actual table of a device\n    \"kernel_routes\": { \n      \"\u003cdevice_name\u003e\": [\n        \"\u003croute\u003e\", # Check the presence of the route in the data-plane of the device\n        \"[\u003croute\u003e, [\u003ciface_name_1\u003e, \u003ciface_name_2\u003e, \u003cnext_hop_1\u003e]]\" # Check the presence of the route in the data-plane of the device\n                                                      # And checks also that the nexthops are set on the correct interfaces\n      ]\n    },\n    \"protocols\": { # Checks on routing protocols\n      \"bgpd\": { # Specific checks for BGP\n        \"neighbors\": { # Check that a peering is up\n          \"\u003cdevice_name\u003e\": [\n            {\"ip\": \u003cneighbour_ip\u003e, \"asn\": \u003cneighbor_asn\u003e}, # Check that a peering is up between the device and \n                                                           # the specified neighbour ip\n          ],\n        },\n        \"networks\": {\n          \"\u003cdevice_name\u003e\": [\n            \"\u003croute\u003e\" # Check that the device announce the route in BGP\n          ],\n        },\n      }, \n      \"\u003cprotocol_name\u003e\": { # General protocol checks\n        \"injections\": { # Check injections into the protocol. Also valid for BGP\n          \"\u003cdevice_name\u003e\": [\n            \"\u003cprotocol_name\u003e\", # Check that the protocol is injected in BGP by the device\n            \"!\u003cprotocol_name\u003e\" # Check that the protocol is not injected in BGP by the device\n          ],\n        }\n      }\n    },\n    \"applications\": {\n      \"dns\": { # Checks on DNS\n        \"authoritative\": {\n          \"\u003czone\u003e\": [\n            \"\u003cip\u003e\" # Check that the authority for the zone is the specified ip \n          ],\n        },\n        \"local_ns\": {\n          \"\u003clocal_ns_ip\u003e\": [\n            \"\u003cdevice_name\u003e\", # Check if the device has the local_ns_ip as local name server.\n          ]\n        },\n        \"records\": {\n\t\t  \"A\": { # The software can check for every type of DNS records\n\t\t\t\"\u003cdns_name\u003e\": [\n\t\t\t\t\"\u003cip\u003e\" # Check if the dns_name is resolved to the ip\n\t\t\t]\n\t\t  }\n        }\n      }\n    },\n    \"reachability\": { # Check reachability between devices\n      \"\u003cdevice_name\u003e\": [\n        \"\u003cip\u003e\", # Check if the device reaches the ip\n        \"\u003cdns_name\u003e\", # Check if the device reaches the dns_name\n      ],\n    },\n\t\"custom_commands\": { # Execute a command inside a device and checks the output\n\t\t\"\u003cdevice_name\u003e\": [\n\t\t\t{\n\t\t\t\t\"command\": \"\u003ccommand\u003e\", # Command to execute\n\t\t\t\t\"regex_match\": \"\u003cregex\u003e\", # Check if the output matches the regex\n\t\t\t\t\"output\": \"\u003cexpected_output\u003e\", # Check if the output is the expected one\n\t\t\t\t\"exit_code\": \u003cexpected_exit_code\u003e # Check if the command exit code is the expected one\n\t\t\t}\n\t\t]\n\t}\n  }\n}\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatharaframework%2Fkathara-lab-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkatharaframework%2Fkathara-lab-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkatharaframework%2Fkathara-lab-checker/lists"}