{"id":18830431,"url":"https://github.com/cmu-sei/greybox","last_synced_at":"2025-04-26T12:32:54.030Z","repository":{"id":50409530,"uuid":"109263996","full_name":"cmu-sei/greybox","owner":"cmu-sei","description":"A tool to host an Internet simulation","archived":false,"fork":false,"pushed_at":"2025-04-25T16:58:10.000Z","size":565,"stargazers_count":54,"open_issues_count":1,"forks_count":17,"subscribers_count":11,"default_branch":"master","last_synced_at":"2025-04-26T10:30:39.861Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Shell","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cmu-sei.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,"zenodo":null}},"created_at":"2017-11-02T12:48:48.000Z","updated_at":"2025-04-25T16:58:14.000Z","dependencies_parsed_at":"2025-04-25T17:14:21.267Z","dependency_job_id":"a55e053e-5258-486e-b23c-025ab0fb095d","html_url":"https://github.com/cmu-sei/greybox","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmu-sei%2Fgreybox","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmu-sei%2Fgreybox/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmu-sei%2Fgreybox/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cmu-sei%2Fgreybox/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cmu-sei","download_url":"https://codeload.github.com/cmu-sei/greybox/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250976118,"owners_count":21516878,"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":[],"created_at":"2024-11-08T01:48:52.221Z","updated_at":"2025-04-26T12:32:54.012Z","avatar_url":"https://github.com/cmu-sei.png","language":"Shell","funding_links":[],"categories":["Infrastructure Tooling"],"sub_categories":[],"readme":"# GreyBox Overview #\nGreyBox is a single-host Internet simulator for offline exercise and\ntraining networks. It allows a single host (physical or VM) to provide\nthe illusion of connectivity to the real Internet: a realistic BGP\nbackbone topology with point-to-point link delays based on physical\ndistance between the routers' real-world locations, combined with\nTopGen's application services (HTTP, DNS, email, etc.).\n\n## Installation ##\nGreyBox depends on the following software packages:\n\n        TopGen\n        CORE (see https://github.com/coreemu/core)\n        FRR (previously Quagga)\n        keepalived\n        dhcp (server)\n\nRunning the './install.sh' script will copy all components of GreyBox\nto the appropriate locations on the filesystem. Also, see\n'./contrib/greybox.spec' for instructions on how to build a GreyBox RPM\npackage.\n\nAn example of pre-installed GreyBox and TopGen on a Fedora 38 VM\n(user = `admin`, password = `tartans`) can be downloaded from:\n\n  - [Virtualbox OVA](http://mirror.ini.cmu.edu/netfor/NetFor38-x86_64.vbx.ova)\n  - [Apple/ARM UTM](http://mirror.ini.cmu.edu/netfor/NetFor38-aarch64.utm.tgz)\n\n## Design ##\nGreyBox relies heavily on TopGen (an application service simulator), and\non the CORE container-based network simulator. In essence GreyBox provides\nan elaborate network topology configuration to be simulated by CORE, with\napplication services to be provide by TopGen. You are encouraged to read\nthe documentation for both TopGen (included with the package), and for\nCORE (at http://downloads.pf.itd.nrl.navy.mil/docs/core/core-html/).\n\n### Networked Containers ###\nAn LXC container is wrapped around each of several instances of FRR's\nbgpd, to allow running them side by side as processes on the same host,\nrather than requiring a dedicated VM, complete with its own running guest\nkernel, to be wrapped around each individual bgpd instance.\n\nIn addition to providing each containerized bgpd instance with its own\ndedicated set of (virtual) network interfaces, the CORE simulator provides\na convenient GUI for visualizing the network topology, facilitates editing\nthe properties of each container and of the inter-container network links\n(implemented as virtual bridges connecting together the virtual interfaces\nassigned to several containers), and allows users to start command shells\nfrom inside each container for further configuration and troubleshooting.\n\nWhile currently popular container orchestration solutions (e.g., Docker)\nare mainly targeted at running pre-packaged software bundles in containers\nwhile minimizing the expectations and dependencies required of the hosting\nserver, CORE is designed to launch multiple instances of native software\nalready present on the host, and is perfectly suited for GreyBox's frugal,\nminimalist use case.\n\n### External Connectivity ###\nNetwork interfaces belonging to the host may be bridged together with\ncontainers' virtual interfaces in a CORE topology map, thus providing\nsimulated Internet access to external machines.\n\n### Routing \u0026 Application Service Reachability ###\nTopGen application services are hosted in a dedicated container, which is\nlinked to every containerized BGP router over a virtual 0-delay Ethernet\nbridge, a.k.a. the \"FTL\" LAN.\n\nAs explained in the TopGen's documentation, the TopGen container will\nrespond to any of a very large set of /32 host IP addresses, all of which\nare configured as secondaries on its loopback interface.\n\nEach BGP router announces a set of static routes to its neighbors, with\nthe next-hop value set to TopGen's FTL network address. Each router will\nannounce a default route, but also a set of more specific /8 routes, the\nunion of which covers all service IPs held by TopGen. The /8 routes\nannounced by each BGP router have been carefully selected to approximately\nmatch their geographic assignment on the real-world Internet.\n\nThe result is that client-originated traffic will travel through a\ngeographically realistic set of hops before being handed over to TopGen\n(via the FTL LAN) by one of the BGP routers announcing the matching /8.\n\n### Return Application Traffic ###\nWhile it is the designated next-hop for *all* routes announced into BGP by\n*every* backbone router, TopGen itself does not run any routing software,\nand no BGP peerings are set up over the FTL virtual LAN. When a TopGen\nservice responds to a client request, reply packets are sourced from the\nsame secondary loopback IP the client traffic was sent to in the first\nplace. All such traffic is forwarded to a virtual default gateway IP\naddress on the FTL network, redundantly supported (through VRRP) by all\nBGP routers on their FTL network interfaces. In practice, it doesn't\nmatter how reply traffic from application services is routed back to the\nclient, since the latter can't even tell, as traceroutes from the client\nreflect only hops on the outbound path.\n\n## Getting Started ##\nAfter installing the GreyBox package and its dependencies, follow this\nbasic process to set up an \"Internet-in-a-box\" GreyBox server:\n\n### Configure TopGen ###\nSee the documentation included with the TopGen package for recursively\nscraping a collection of web sites, setting up virtual email domains,\nand configuring multiple root, top-level, and caching name servers. Do\nnot enable or start any TopGen services: TopGen will be brought up by the\nCORE network simulator as a container, using a different set of startup\nscripts.\n\n*NOTE:* To allow TopGen's DNS service to resolve point-to-point BGP router\ninterfaces, the IP address to FQDN hostname mappings must be loaded into\nthe DNS database, using the following command:\n\n        topgen-mkdns.sh -f -x /usr/share/greybox/etc/backbone.hosts\n\n### Configure Nameserver(s) on GreyBox Host ###\nIt is recommended that name servers in '/etc/resolv.conf' be set to\n8.8.8.8 and/or 8.8.4.4. CORE containers retain access to most of the host\nfilesystem (except for explicitly assigned, dedicated subdirectories, e.g.\n'/var/log/'), and will thus refer to the TopGen-provided 8.8.8.8 and\n8.8.4.4 addresses for in-game DNS resolution. If the GreyBox host retains\naccess to the *real* Internet, processes not part of the simulation will\nbe directed to the real Google-provided caching DNS servers at the same\naddresses, by the same '/etc/resolv.conf' file.\n\n### Load a GreyBox Network Map ###\nThe GreyBox package ships with two Internet simulation maps (in the\n'/usr/share/greybox/maps/' folder):\n\n        backbone.imn: an entirely self-contained Internet simulation, with\n                      69 BGP backbone router containers, a TopGen service\n                      container, and two \"client laptop\" containers for\n                      running tests (e.g. traceroute, dns resolution, text\n                      mode email with mailx or mutt, etc.).\n\n        backbone_ext.imn: same as above, except with one of the \"client\"\n                          containers replaced with an RJ-45 \"ethernet\"\n                          port, which may be mapped to one of the GreyBox\n                          host's network interfaces, which allows the\n                          Internet simulation to be accessed over the\n                          network from outside the GreyBox machine itself.\n                          *NOTE:* This file must be edited before use, to\n                          replace \"ethX\" with the name of one of the real\n                          network interfaces available on the GreyBox host.\n\nFirst, ensure that the CORE daemon service is running:\n\n        systemctl start core-daemon\n\nThen, from a terminal window, load a simulation map into the CORE GUI:\n\n        core-gui /usr/share/greybox/maps/backbone.imn\n\nWhen the GUI is up, press the green \"play\" button to start the simulation.\nOnce the simulation is fully underway, right-click on any of the container\nicons to select \"Shell Window -\u003e bash\" to get a terminal window from the\ninside perspective of that specific container. On containers representing\nBGP routers, one may select \"Shell Window -\u003e vtysh\" for direct access to\nthe Cisco-like user interface exposed by the FRR shell.\n\n### Loading a GreyBox Map at Boot ###\nThe GreyBox package also ships with a systemd service which, when enabled:\n\n        systemctl enable greybox\n\nwill load and start a simulation map when the GreyBox host machine boots.\nThe default map, '/etc/greybox/map.imn', ships as an identical clone of\nthe self-contained '/usr/share/greybox/maps/backbone.imn', and, as such,\ncan be used immediately without modification. However, if external access\nto the simulation is required, one must edit '/etc/greybox/map.imn' using\ne.g., '/usr/share/greybox/maps/backbone_ext.imn' as a starting point.\n\n### External Connectivity Considerations ###\nRecent Linux installs tend to use unpredictable naming conventions for\nthe host's network interfaces, from the traditional 'eth0' to names like\n'ens32' or 'enp11s0'. Before using a network map file designed for outside\nconnectivity (e.g., '/usr/share/greybox/maps/backbone_ext.imn'), be sure\nto replace the placeholder string \"ethX\" with the name of the real host\ninterface you wish to dedicate to the simulation.\n\nAdditionally, ensure that interfaces dedicated to the simulation are not\nmanaged by any host networking sybsystem (e.g., NetworkManager on RedHat\nflavored distributions). In the simplest case, if *all* host interfaces\nare assigned to the simulation, NetworkManager may be turned off entirely:\n\n        systemctl stop NetworkManager\n        systemctl disable NetworkManager\n\nAlternatively, any interface dedicated to the simulation can be marked as\noff-limits to NetworkManager by adding the line \"NM_CONTROLLED=no\" to its\n'/etc/sysconfig/network-scripts/ifcfg-ethX' config file. Similar steps\nexist (and should be followed) on distributions which are not following\nRedHat/Fedora conventions.\n\n\u003chr\u003e\nFor ***best effort*** help, post your question in the `#greybox` (freenode)\nIRC channel.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmu-sei%2Fgreybox","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcmu-sei%2Fgreybox","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcmu-sei%2Fgreybox/lists"}