{"id":20326055,"url":"https://github.com/matteoguadrini/vmam","last_synced_at":"2025-04-11T20:06:23.359Z","repository":{"id":62587680,"uuid":"216534900","full_name":"MatteoGuadrini/vmam","owner":"MatteoGuadrini","description":"VLAN Mac-address Authentication Manager","archived":false,"fork":false,"pushed_at":"2021-04-05T20:01:58.000Z","size":405,"stargazers_count":24,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-04-11T20:06:21.869Z","etag":null,"topics":["80211","8021x","ieee8021x","ldap","ldap-authentication","ldap-group","ldap-manager","ldap-server","ldap3","mab","mac-address","nac","network-architecture","python3","pywinrm","radius","radius-server","rfc-3579","vlan"],"latest_commit_sha":null,"homepage":"https://matteoguadrini.github.io/vmam/","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/MatteoGuadrini.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGES.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE.md","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2019-10-21T09:55:27.000Z","updated_at":"2024-07-20T13:45:09.000Z","dependencies_parsed_at":"2022-11-03T17:48:09.490Z","dependency_job_id":null,"html_url":"https://github.com/MatteoGuadrini/vmam","commit_stats":null,"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fvmam","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fvmam/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fvmam/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MatteoGuadrini%2Fvmam/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MatteoGuadrini","download_url":"https://codeload.github.com/MatteoGuadrini/vmam/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248473127,"owners_count":21109628,"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":["80211","8021x","ieee8021x","ldap","ldap-authentication","ldap-group","ldap-manager","ldap-server","ldap3","mab","mac-address","nac","network-architecture","python3","pywinrm","radius","radius-server","rfc-3579","vlan"],"created_at":"2024-11-14T19:42:46.430Z","updated_at":"2025-04-11T20:06:23.333Z","avatar_url":"https://github.com/MatteoGuadrini.png","language":"Python","funding_links":["https://www.paypal.me/guos"],"categories":[],"sub_categories":[],"readme":"# vmam: VLAN Mac-address Authentication Manager\n\n\u003cimg src=\"https://raw.githubusercontent.com/MatteoGuadrini/vmam/master/img/vmam.png\" alt=\"vmam\" title=\"vmam\" width=\"210\" height=\"210\" /\u003e\n\u003cbr\u003e\n\u003cbr\u003e\n\n[![Codacy Badge](https://api.codacy.com/project/badge/Grade/7fc47024f17f4dffa3be08a7a5ab31bd)](https://app.codacy.com/app/MatteoGuadrini/vmam?utm_source=github.com\u0026utm_medium=referral\u0026utm_content=MatteoGuadrini/vmam\u0026utm_campaign=Badge_Grade_Dashboard)\n[![CircleCI](https://circleci.com/gh/MatteoGuadrini/vmam.svg?style=svg)](https://circleci.com/gh/MatteoGuadrini/vmam)\n\n`vmam` is a Free and Open Source network access control (NAC) solution. \nthat access the network under a specific domain and a specific VLAN, through LDAP authentication and RADIUS server.\nThis is based on [RFC 3579](https://tools.ietf.org/html/rfc3579#section-2.1).\n\n## Python module dependencies\n\n- [x] [pywinrm](https://github.com/diyan/pywinrm)\n- [x] [ldap3](https://github.com/cannatag/ldap3)\n- [x] [deamon](https://pagure.io/python-daemon/)\n- [x] [pyyaml](https://pyyaml.org/)\n\n## What's vmam?\n\n**vmam** is a Free and Open Source command line tool and python module, which manages, manually or automatically, \naccess to the network based on the configurations of its network equipment through LDAP server (Active Directory, FreeIPA, etc.) and \nRADIUS server (Microsoft Radius or Free Radius) see [IEEE 802.1X](https://en.wikipedia.org/wiki/IEEE_802.1X), \nbased on [RFC 3580](https://tools.ietf.org/html/rfc3580), [RFC 4014](https://tools.ietf.org/html/rfc4014),\n[RFC 2865](https://tools.ietf.org/html/rfc2865), [RFC 3579](https://tools.ietf.org/html/rfc3579).\n\n### vmam architecture\n\n_vmam_ is a server-side application. Work with an open source LDAP server or Active Directory. \nBasically it creates mac-address users that represent the network card of a machine and associates these users with LDAP groups \nthat represent the various VLANs specified created on their own network architecture (wi-fi, switches, routers, firewalls, etc.), \ncentralized wired and wireless management, with 802.1X support.\nIn addition, based on its configuration, it can also associate computer accounts with this group to allow access to the network \nby spending the credentials of the computer account.\n\n_vmam_ can be installed on a Unix base server. The computer accounts linked to the domain, for only automatic mode must be Microsoft Windows.\nManual mode work with only mac-address user and therefore the operating system is indifferent.\n\n## How do you do it?\n\n**vmam** is installed as a server. \n\n\n## Installation\n\nThe installation of *vmam* is very simple. With *pip*:\n\n```bash\npip install vmam\n```\n\nOr just run these commands:\n\n```bash\ngit clone https://github.com/MatteoGuadrini/vmam.git\ncd vmam\nsudo python3 setup.py install\n```\n\n### Manual mode\n\nIn manual mode, mac-addresses are managed from the command line using the `vmam mac` command.\nThe *mac* command has options to add, remove and disable the mac-addresses that can access the network.\nFor more details, [see the docs](https://vmam.readthedocs.io/en/latest/cmd.html#manual-mode).\n\n### Automatic mode\n\nIn automatic mode, mac-addresses are managed by contacting LDAP server and taking the last machines (variable in the configuration file) \nthat contacted the LDAP server from _N_ seconds, minutes, hour or days, depending on the needs and policies decided.\n\n\u003e Attention: Clients must have WINRM active. See the `winrm quickconfig` command. \n\nThis mode is activated by launching `vmam start` on the command line. \nWithout any parameter, it reads the configuration file (if not specified, the default one), \ncontacts ldap, takes the last machines that contact the LDAP server, contacts them via WinRM, \ntakes the information of the last connected user and the tabs of active network, LDAP check to see which VLAN-ID (LDAP group)\nassign to the mac-address and then exit.\n\nIf you were to specify the `--daemon/-d` argument then the process would continue until a manual interrupt (kill the process).\n\nFor more details, [see the docs](https://vmam.readthedocs.io/en/latest/cmd.html#automatic-mode).\n\n\n## How to start\n\nLet's start with our network architecture.\n\n### Configure network architecture and radius server\n\nBefore starting to use `vmam`, you need to know your network architecture and configure it correctly.\nRead these RFCs carefully ([RFC 3580](https://tools.ietf.org/html/rfc3580), [RFC 4014](https://tools.ietf.org/html/rfc4014),\n[RFC 2865](https://tools.ietf.org/html/rfc2865), [RFC 3579](https://tools.ietf.org/html/rfc3579)) and choose a radius server based on your architecture \n([freeradius](https://freeradius.org/) or [Microsoft Radius](https://docs.microsoft.com/it-it/windows-server/networking/technologies/nps/nps-top)).\n\nOnce the network equipment and radius server have been configured, create ldap groups corresponding to the VLAN that you want to manage. \n\ne.g .: *VLAN_ID 100 on switch to group LDAP VLAN100.*\n\nThis VLAN100 group must be configured on the VLAN ID in the radius server corresponding to the VLAN100 group.\n\n### Get configuration by vmam\n\nYou can configure _vmam_ before configuring your network architecture.\n\nYou can start creating a default file by typing: `vmam config --new`\n\nThis will create a standard configuration file under `/etc/vmam/vmam.conf`.\n\nNow it will be enough, edit and customize the configuration file following the documentation as guidelines. Once done, type `vmam config --get-cmd`\n\nThis command will return the guide to correctly configure LDAP and the radius server based on the configuration file.\n\n## Python module\n\n_vmam_ can also be used as a python module, to build your own scripts to manage mac addresses that access the network.\n\nHere is a simple script to add mac addresses from a file.\n\n```python\nfrom vmam import *\n# activate debug\ndebug = True\n# log writer\nwt = logwriter('/tmp/log.log')\n# start script\ndebugger(debug, wt, 'Start...')\n# connect to LDAP server\nconn = connect_ldap(['dc1.foo.bar'])\nbind = bind_ldap(conn, r'domain\\admin', 'password', tls=True)\nldap_version = check_ldap_version(bind, 'dc=foo,dc=bar')\nfor mac in get_mac_from_file('/tmp/mac_list.txt'):\n    debugger(debug, wt, 'create mac address {}'.format(mac))\n    # create mac address\n    dn = 'cn={},ou=mac,dc=foo,dc=bar'.format(mac)\n    attrs = {'givenname': 'mac-address',\n                'sn': mac,\n                'samaccountname': mac\n            }\n    # create mac-address user\n    new_user(bind, dn, **attrs)\n    # add mac user to vlan group\n    add_to_group(bind,   'cn=vlan_group100,ou=groups,dc=foo,dc=bar', dn)\n    # set password and password never expires\n    set_user(bind, dn, pwdlastset=-1, useraccountcontrol=66048)\n    set_user_password(bind, dn, mac, ldap_version=ldap_version)\n```\n\n## Documentation\nThe official documentation for more details of configuration and implementations, is here: [docs](https://vmam.readthedocs.io/en/latest/)\n\n## Open source\n_vmam_ is a open source project. Any contribute, It's welcome.\n\n**A great thanks**.\n\nFor donations, press this\n\nFor me\n\n[![paypal](https://www.paypalobjects.com/en_US/i/btn/btn_donateCC_LG.gif)](https://www.paypal.me/guos)\n\nFor [Telethon](http://www.telethon.it/)\n\nThe Telethon Foundation is a non-profit organization recognized by the Ministry of University and Scientific and Technological Research.\nThey were born in 1990 to respond to the appeal of patients suffering from rare diseases.\nCome today, we are organized to dare to listen to them and answers, every day of the year.\n\n\u003ca href=\"https://www.telethon.it/sostienici/dona-ora\"\u003e \u003cimg src=\"https://www.telethon.it/dev/_nuxt/img/c6d474e.svg\" alt=\"Telethon\" title=\"Telethon\" width=\"200\" height=\"104\" /\u003e \u003c/a\u003e\n\n[Adopt the future](https://www.ioadottoilfuturo.it/)\n\n\n## Acknowledgments\n\nThanks Alexey Diyan for pywinrm module; thanks Giovanni Cannata for ldap3 module; thanks Ben Finney for python-daemon module; thanks to all yaml team.\n\nThanks to Mark Lutz for writing the _Learning Python_ and _Programming Python_ books that make up my python foundation.\n\nThanks to Kenneth Reitz and Tanya Schlusser for writing the _The Hitchhiker’s Guide to Python_ books.\n\nThanks to Dane Hillard for writing the _Practices of the Python Pro_ books.\n\nSpecial thanks go to my wife, who understood the hours of absence for this development. \nThanks to my children, for the daily inspiration they give me and to make me realize, that life must be simple.\n\nThanks Python!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteoguadrini%2Fvmam","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmatteoguadrini%2Fvmam","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmatteoguadrini%2Fvmam/lists"}