{"id":20588821,"url":"https://github.com/ciscodevnet/mud-manager","last_synced_at":"2026-03-11T08:02:28.453Z","repository":{"id":48923540,"uuid":"136672356","full_name":"CiscoDevNet/MUD-Manager","owner":"CiscoDevNet","description":"Manufacturer Usage Description (MUD) is a technique whereby constrained end devices (e.g., IoT devices) can signal to the network what sort of access and network functionality they require to properly function","archived":false,"fork":false,"pushed_at":"2021-07-05T13:31:34.000Z","size":1162,"stargazers_count":23,"open_issues_count":11,"forks_count":10,"subscribers_count":22,"default_branch":"master","last_synced_at":"2025-07-23T13:50:46.130Z","etag":null,"topics":["ietf","iot","testing-tools"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CiscoDevNet.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-06-08T22:44:19.000Z","updated_at":"2025-05-25T13:16:47.000Z","dependencies_parsed_at":"2022-08-12T19:51:17.891Z","dependency_job_id":null,"html_url":"https://github.com/CiscoDevNet/MUD-Manager","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/CiscoDevNet/MUD-Manager","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FMUD-Manager","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FMUD-Manager/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FMUD-Manager/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FMUD-Manager/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CiscoDevNet","download_url":"https://codeload.github.com/CiscoDevNet/MUD-Manager/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CiscoDevNet%2FMUD-Manager/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":30375481,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-03-11T06:09:32.197Z","status":"ssl_error","status_checked_at":"2026-03-11T06:09:17.086Z","response_time":84,"last_error":"SSL_read: 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":["ietf","iot","testing-tools"],"created_at":"2024-11-16T07:26:33.553Z","updated_at":"2026-03-11T08:02:28.434Z","avatar_url":"https://github.com/CiscoDevNet.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"![alt text](./MUDlogo.jpg)\n\n\n\n# MUD-Manager Version 3.0\n\n\n### A list of changes can be found down below.\n\n## Introduction\n\nManufacturer Usage Description (MUD) is a technique whereby constrained end devices (e.g., IoT devices) can signal to the network what sort of access and network functionality they require to properly function. The end device performs this signaling by issuing a URL in LLDP, DHCP, or as part of an X.509 certificate. A MUD Manager is a service sitting in the network that receives the MUD URL, fetches a MUD file containing access requirements provided by a manufacturer, and creates Access Control Lists (ACLs) that can be installed on network equipment to allow that access.\n\nThe MUD specification can be found in\n(https://tools.ietf.org/html/draft-ietf-opsawg-mud-25), which has been approved to be an IETF RFC.  This implementation supports all abstractions, except model.  In addition, source and destination IPv4 and IP networks from the ACL model are supported, so long as they are multicast addresses.\n\nAfter you have installed the MUD Manager, guidance is available at (https://developer.cisco.com/docs/mud/#!mud-developer-guide) if you need help creating a MUD file, and/or preparing a device to emit a URL to a MUD file.\n\n## How the MUD Manager is used\nThe MUD Manager is used by a RADIUS server to translate a MUD URL into access control policies. The MUD Manager receives REST APIs containing the MUD URL (and possibly other information), and returns RADIUS attributes that can be sent to a Network Access Device (NAD) such as an Ethernet switch. The NAD installs the policy on the access port, which restricts the device providing the MUD URL to just its required network access.\n\nA MUD URL is an \"https://...\" file, which means that TLS is used to fetch the file.\n\n## Dependancies\nThe MUD manager depends on the following packages.\n\n### OpenSSL\nOpenSSL is used for cryptographic services, and is available on most Linux systems. If not, then a recent release will need to be installed. It may be available using a package installer (such as apt-get), else it can be downloaded from https://www.openssl.org. \n\nIf a Linux distribution has openssl, but you cannot link to it try:\n\n```bash\nsudo apt-get install -y libssl-dev # debian\n```\n\nor\n```bash\nyum install openssl-devel # centos\n```\n\n### cJSON\ncJSON is used for JSON processing in \"C\". Download it from \n[GitHub](https://github.com/DaveGamble/cJSON):\n\n```bash\ngit clone https://github.com/DaveGamble/cJSON\ncd cJSON \nmake\nsudo make install\n```\n\n\n### MongoDB\nMongoDB is used to store the MUD URLs, policy derived from the MUD URLs, and MAC addresses that are associated with a MUD URL.\n\nInstructions for installing MongoDB with a package manager can be found \n[here](https://docs.mongodb.com/manual/administration/install-on-linux/). \nAlternatively it can be downloaded with git, and the follow the instructions in its `README`.\n\n```bash\ngit clone https://github.com/mongodb/mongo.git\n```\n\n\nThe MongoDB service should be started automatically when the system boots. If you see an indication that the MUD Manager cannot reach the MongoDB server, you can try\n\n```bash\nsudo service mongodb start # (Recent Debian/Ubuntu releases)\nsudo /etc/init.d/mongod start # Amazon/CentOS\\\n```\n\n### Mongo C driver\nThe Mongo C driver is needed for the MUD manager to communicate with MongoDB. Download from https://github.com/mongodb/mongo-c-driver/releases. We suggest version `1.7.0` or later, but in any case a version that supports PKG-CONFIG (this excludes the Debian package manager).\n\nTo retrieve, make and install `1.7.0`:\n\n```bash\nwget https://github.com/mongodb/mongo-c-driver\ncd mongo-c-driver\ncmake\nmake\nsudo make install\n```\n\n### libcurl\nLibcurl is used to fetch MUD files from a MUD file server.\n```bash\nsudo apt-get install libcurl4-openssl-dev # Debian/Ubuntu\n```\nor\n```bash\nsudo yum install libcurl-devel # CentOS/Amazon\n```\n\n \nIf you retrieve libcurl and build it on your own, you may wish to\nbuild against `OpenSSL` rather than `GNUTLS`, as the latter dramatically\nincreases the number of dependencies (this includes such things as\nthe `GSSAPI` and `MySQL`, which are really unused in this case).\n\n## Building the MUD Manager\n\nRun configure and make. \n \n ```bash\n./configure \nmake\nsudo make install\n ```\n \n## Editing the configuration file.\nThe default location for the configuration file is:\n\n```bash\n/usr/local/etc/mud_manager_config.json\n```\n\nThe following fields can be set in the configuration file.\n\n#### 1. MUDManagerAPIProtocol\n\nThis defines whether the REST APIs should be `http://` or `https://`. The \ndefault configuration file setting is `http://`.\n\nIf `https://` is used, then the MUD Manager will also need the following TLS-related fields added:\n\n* `MUDManager_cert`, with a pathname to the MUD Manager's signing certificate\n* `MUDManager_key`, with a pathname to the MUD Manager's private key\n* `Enterprise_CACert`, with a pathname to the CA certificate that signed the `MUDManager_cert`\n\n#### 2. Default_VLAN\n\nThis provides for a VLAN when same-manufacturer is not used.\n\n#### 3. ACL_Type\n\nThis directs the MUD manager to return ACLs only to enforce policy on the \"ingress\" direction (i.e., from the device), or whether to enforce policy on both ingress and egress (i.e., to and from the device). Its setting depends on the capabilities of the NAD. \n\nThe safest choice is to leave it as `dACL-ingress-only`, however if you have a NAD that will also enforce egress policy you should set it as `dACL-ingress-egress`.\n\n#### 4. COA_Password\nIn some cases, a RADIUS server will complete an  Authentication exchange for a device before the NAD gives it a MUD URL associated with that device. When the association is subsequently made, the MUD policy will not become effective on the NAD before the next Authentication session. A convenient way to cause the Authentication to happen is for the MUD manager to send a Change of Authorization (CoA) to the NAD, instructing it to perform authentication with the RADIUS server again.\n\nFor the CoA to succeed, the MUD Manager must share a password with the NAD. Replace the sample password provided in the configuration file with the password you use on the NAD.\n\n#### 5. VLANs\n\nIf the `VLANs` array is present, it consists of a pool of VLANs\navailable for assignment when `same-manufacturer` is present for a\ngiven authority.  These will be automatically assigned, and stored in\nMUD-Manager's internal database.  If they are removed from the\nconfiguration file, they will *still* be used.  If a `vlan` field\nexists for a particular manufacturer, it will override the use of the\npool.\n\nEach array entry consists of the following elements:\n\n * `VLAN_ID`: the value of the VLAN to be used.\n * `v4addrmask`: a string in the form of a dotted quad\n   and a wildcard mask also in the form of a dotted quad.  For example:\n   ```\n    \"v4addrmask\" : \"192.168.1.0 0.0.0.255\"\n   ```\n   \n * `v6addrmask`: a string in the form of a v6 network and a mask.\n \n**Note Bene** all VLANs listed in configuration or in the database\n  must have previously been configured in all switches using the same\n  AAA server.\n\n#### 6. Manufacturers\n\nThis array of manufacturers is optional.  When present, it may contain information that includes an authority string, a set of certificates for validation, an optional VLAN, my-controller information for this particular instance, and any local network information to be used.  If NOT present, the MUD manager will press on, but my-controller statements will be ignored.  See below for more detail.\n\n\n##### 6.1 authority\n\nThe authority portion of the URL, which defines the unique manufacturer. For\nexample, if the URL is `\"https://luminaire.example.com/Luminaire_150\"`, the\nauthority portion of the URL is `\"luminaire.example.com\"`. This same string\nneeds to be placed in the authority policy of the Manufacturer in the\nconfiguration file.\n\n##### 6.2 cert\n\nThe CA certificate for the manufacturer, which is used to verify the MUD file server signature.\n\n##### 6.3 https_port\n\nThe port used to contact the file server (e.g., 443).\n\n##### 6.4 my_controller_v4, my_controller_v6\n\nThese are used to define what is the local IP address for a \"my-controller\" statement found in a MUD file.  If these are not present, the my-controller statement will be ignored.\n\n##### 6.5 local_networks_v4, local_networks_v6\n\nThese are used to translate a \"local-networks\" statement found in a MUD file.\n\n##### 6.6 vlan\n\nIf a \"same-manufacturer\" statement is found in the MUD file, this VLAN\nvalue is sent with the ACLs to the NAD. This field generally should\nnot be used.  Instead, create a group of VLAN entries in the VLANs\narray and allow MUD Manager to assign them.\n\n##### 6.7 v4addrmask, v6addrmask\n\nFor the VLAN there needs to be a statement such as \"192.168.1.0 0.0.0.255\" (or equivalent v6) to permit acces to that VLAN.\n\n##### 6.8 DNSMapping, DNSMapping_v6\n\nIf a MUD file has a DNS name in it, and that name is not resolvable (say because you are doing testing), you can add a translation here.  If you do not, a DNS lookup will be performed.\n\n##### 6.9 ControllerMapping, ControllerMapping_v6\n\nIf a MUD file has a \"controller\" statement, it needs to be translated to an IP address. Do that here.\n\n##### 6.10 DefaultACL, DefaultACL_v6\n\nA site policy may provide additional restrictions to the devices. These can be defined as access control list statements here. The default policy included in the configuration policy is to block all other IP and ICMP packets.\n\n## MongoDB Tools\n\nTwo scripts are included to manipulate the MUD Manager collections in MongoDB.\n  * `mud_clobber_db`: This can be used to clean out the MUD Manager \n  collections, which forces MUD files to be fetched and access policy to be re-gererated.\n  * `mud_show_db`: This displays the contents of the three collections used \n  by the MUD Manager.\n\n## Examples\n\nThe examples directory includes an example of a \"luminaire\", which includes a sample MUD file, sample MUD file server, certificates, and instructions how to use the mud_test_command to invoke the MUD Manager. \n\n## MUD Manager Test Command\n\nA simple test command is included, which imitates REST APIs to the MUD Manager and verifies that the MUD Manager can download and process a  MUD file.\n\nIf the \"luminaire\" example MUD file server is running, and the MUD manage is started on its default port, then the following test command should retrieve the MUD file and the return the ACLs contained within it.\n\n```bash\nmud_test_client -f Luminaire_150 -c 127.0.0.1 -p 8000 -w luminaire.example.com\n```\n    \n\nThe output should look something like this:\n\n```bash\nURL:  https://luminaire.example.com/Luminaire_150\n\nStarting RESTful client against http://127.0.0.1:8000/getaclname\n    with request {\n        \"MUD_URI\":      \"https://luminaire.example.com/Luminaire_150\"\n}\nGot ACL Names\nFull ACL Name 0: ACS:CiscoSecure-Defined-ACL=mud-21966-v4fr.in\nACLname: mud-21966-v4fr.in\n\nStarting RESTful client against http://127.0.0.1:8000/getaclpolicy with request {\n        \"ACL_NAME\":     \"mud-21966-v4fr.in\"\n}\nUsername: mud-21966-v4fr.in\nGot DACL contents:\n        ACE: ip:inacl#10=permit tcp any host 172.12.212.10 range 443 443 established\n        ACE: ip:inacl#20=permit udp any host 10.1.1.4 range 5684 5684\n        ACE: ip:inacl#30=permit udp any host 255.255.255.255 range 5683 5683\n        ACE: ip:inacl#40=permit tcp any eq 22 any\n        ACE: ip:inacl#41=deny ip any any\n```\n\n# The Web User Interface\n\nA new web user interface is now available just for testing purposes.\n**Beware** that there is no current authentication mechanism.\n\nPrerequisites:\n\n * PHP 2.7 or later\n * The PHP mongodb extension.\n * composer\n\nThe configure script will not test for PHP or mongodb, but will test for\ncomposer.\n\nTo install, issue the configure command with --with-webui=/installdirectory\nwhere the installdirectory is where you want the HTML installed.\n\n\n# What's new for 3.0?\n\n * Basic UI support. \n * Multicast support.  MUD files can contain multicast addresses.\n * Source tree reorganized.\n * VLAN support improved\n * Support for new RESTful endpoint to update server\n * Github space correction.\n \n\n\n# What's New for 2.0?\n\nThe latest code contains a great many bug fixes and a number of\nadditions.  Here's a brief list:\n\n * Limit of 11 ACE lines removed.  Memory is now realloced as required.\n * VLANs are pulled from a pool.  Manufacturer entries should not list them.\n * The config file is now versioned.\n * Add a default for local-networks\n * Fix a memory corruption issue.\n * Relax the idea that somehow \"protocol\" was required in the MUD file.\n * Relax the MIME check on MUD files.  Yes, MUD File Servers should use \n   application/json, but as most people are just going to use apache,\n   let's not be too pedantic.\n\nTo begin with, you don't need to list a manufacturer in\nthe config file.  Until you do, of course, the controller functions\nare quite limited.  We are also now using the updated MUD\nspecification, reading in all the informational elements into the\nMongoDB.  This will become more important later on as we begin to\noffer at least something of a graphical interface to All of This.\n\n## Contributors\nRashmikant Shah\n\n[Brian Weis](https://github.com/iggy2028)\n\n[Cheryl Madson](https://github.com/cmadsoncisco)\n\n[Eliot Lear](https://github.com/elear)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fmud-manager","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fciscodevnet%2Fmud-manager","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fciscodevnet%2Fmud-manager/lists"}