vmam module

VLAN Mac-address Authentication Manager

vmam is a command line tool which allows the management and maintenance of the mac-addresses that access the network under a specific domain and a specific VLAN, through LDAP authentication. This is based on RFC-3579(https://tools.ietf.org/html/rfc3579#section-2.1).

Usage for command line:

SYNOPSYS

vmam [action] [parameter] [options]

config {action}: Configuration command for vmam environment

    --new/-n {parameter}: Instruction to create a new configuration file. By specifying a path, it creates the
    file in the indicated path. The default path is /etc/vmam/vmam.cfg

    $> vmam config --new
    Create a new configuration in a standard path: /etc/vmam/vmam.cfg

    --get-cmd/-g {parameter}: Instruction to obtain the appropriate commands to configure your network
    infrastructure and radius server around the created configuration file. By specifying a path, get
    the file in the indicated path. The default path is /etc/vmam/vmam.cfg

    $> vmam config --get-cmd
    It takes instructions to configure its own network and radius server structure,
    from standard path: /etc/vmam/vmam.cfg

start {action}: Automatic action for vmam environment

    --config-file/-c {parameter}: Specify a configuration file in a custom path (optional)

    $> vmam start --config-file /home/arthur/vmam.cfg
    Start automatic process based on custom path configuration file: /home/arthur/vmam.cfg

    --daemon/-d {parameter}: If specified, the automatic process run in background

    $> vmam start --daemon
    Start automatic process in background based on standard path: /etc/vmam/vmam.cfg

mac {action}: Manual action for adding, modifying, deleting and disabling of the mac-address users

    --add/-a {parameter}: Add a specific mac-address on LDAP with specific VLAN. See also --vlan-id/-i

    $> vmam mac --add 000018ff12dd --vlan-id 110
    Add new mac-address user with VLAN 110, based on standard configuration file: /etc/vmam/vmam.cfg

    $> vmam mac --add 000018ff12dd --vlan-id 111
    Modify new or existing mac-address user with VLAN 111, based on standard configuration
    file: /etc/vmam/vmam.cfg

    --description/-D {parameter}: Add description on created mac-address

    $> vmam mac --add 000018ff12dd --vlan-id 110 --description "My personal linux"
    Add new mac-address user with VLAN 110, based on standard configuration file: /etc/vmam/vmam.cfg

    --remove/-r {parameter}: Remove a mac-address user on LDAP

    $> vmam mac --remove 000018ff12dd
    Remove mac-address user 000018ff12dd, based on standard configuration file: /etc/vmam/vmam.cfg

    --disable/-d {parameter}: Disable a mac-address user on LDAP, without removing

    $> vmam mac --disable 000018ff12dd
    Disable mac-address user 000018ff12dd, based on standard configuration file: /etc/vmam/vmam.cfg

    --force/-f {parameter}: Force remove/disable action

    $> vmam mac --remove 000018ff12dd --force
    Force remove mac-address user 000018ff12dd, based on standard configuration file: /etc/vmam/vmam.cfg

    --vlan-id/-i {parameter}: Specify a specific VLAN-id

    $> vmam mac --add 000018ff12dd --vlan-id 100
    Add new mac-address user with VLAN 100, based on standard configuration file: /etc/vmam/vmam.cfg

    --config-file/-c {parameter}: Specify a configuration file in a custom path (optional)

    $> vmam mac --remove 000018ff12dd --config-file /opt/vlan-office/office.cfg
    Remove mac-address user 000018ff12dd, based on custom configuration file: /opt/vlan-office/office.cfg

--version/-V {option}: Print version and exit

--verbose/-v {option}: Print and log verbose information, for debugging

Usage like a module:

#!/usr/bin/env python3
from vmam import *

# activate debug
debug = True

# define log writer
wt = logwriter('/tmp/log.log')

# start script
debugger(debug, wt, 'Start...')

# connect to LDAP server
conn = connect_ldap(['dc1.foo.bar'])
bind = bind_ldap(conn, r'domain\admin', 'password', tls=True)
ldap_version = check_ldap_version(bind, 'dc=foo,dc=bar')

for mac in get_mac_from_file('/tmp/mac_list.txt'):
    debugger(debug, wt, 'create mac address {}'.format(mac))
    # create mac address
    dn = 'cn={},ou=mac,dc=foo,dc=bar'.format(mac)
    attrs = {'givenname': 'mac-address',
                'sn': mac,
                'samaccountname': mac
            }
    # create mac-address user
    new_user(bind, dn, **attrs)
    # add mac user to vlan group
    add_to_group(bind, 'cn=vlan_group100,ou=groups,dc=foo,dc=bar', dn)
    # set password and password never expires
    set_user(bind, dn, pwdlastset=-1, useraccountcontrol=66048)
    set_user_password(bind, dn, mac, ldap_version=ldap_version)

AUTHOR

Matteo Guadrini <matteo.guadrini@hotmail.it>

COPYRIGHT

3. Matteo Guadrini. All rights reserved.

vmam.logwriter(logfile)

Logger object than write line in a log file

Parameters:logfile – Path of logfile(.log) Returns:Logger object

>>> wl = logwriter('test.log')
>>> wl.info('This is a test')

vmam.debugger(verbose, writer, message)

Debugger: write debug and print verbose message

Parameters:

• verbose – verbose status; boolean
• writer – Log writer object
• message – String message

Returns:

String on stdout

>>> wl = logwriter('test.log')
>>> debugger(True, wl, 'Test debug')

vmam.confirm(message)

Confirm action

Parameters:message – Question that expects a ‘yes’ or ‘no’ answer Returns:Boolean

>>> if confirm('Please, respond'):
...    print('yep!')

vmam.read_config(path)

Open YAML configuration file

Parameters:path – Path of configuration file Returns:Python object

>>> cfg = read_config('/tmp/vmam.yml')
>>> print(cfg)

vmam.get_platform()

Get a platform (OS info)

Returns:Platform info dictionary

>>> p = get_platform()
>>> print(p)

vmam.new_config(path='/etc/vmam/vmam.yml')

Create a new vmam config file (YAML)

Parameters:path – Path of config file Returns:None

>>> new_config('/tmp/vmam.yml')

vmam.bind_ldap(server, user, password, *, tls=False)

Bind with user a LDAP connection

Parameters:

• server – LDAP connection object
• user – user used for bind
• password – password of user
• tls – if True, start tls connection

Returns:

LDAP bind object

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> print(bind)

vmam.check_connection(ip, port, timeout=3)

Test connection of remote (ip) machine on (port)

Parameters:

• ip – ip address or hostname of machine
• port – tcp port
• timeout – set timeout of connection

Returns:

Boolean

>>> check_connection('localhost', 80)

vmam.check_config(path)

Check YAML configuration file

Parameters:path – Path of configuration file Returns:Boolean

>>> cfg = check_config('/tmp/vmam.yml')

vmam.connect_ldap(servers, *, ssl=False)

Connect to LDAP server (SYNC mode)

Parameters:

• servers – LDAP servers list
• ssl – If True, set port to 636 else 389

Returns:

LDAP connection object

>>> conn = connect_ldap(['dc1.foo.bar'], ssl=True)
>>> print(conn)

vmam.unbind_ldap(bind_object)

Unbind LDAP connection

Parameters:bind_object – LDAP bind object Returns:None

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> bind.unbind()

vmam.query_ldap(bind_object, base_search, attributes, comp='=', **filters)

Query LDAP

Parameters:

• bind_object – LDAP bind object
• base_search – distinguishedName of LDAP base search
• attributes – list of returning LDAP attributes
• comp –

  comparison operator. Default is ‘=’. Accepted:

  Equality (attribute=abc) =

  Negation (!attribute=abc) !

  Presence (attribute=*) =*

  Greater than (attribute>=abc) >=

  Less than (attribute<=abc) <=

  Proximity (attribute~=abc) ~=

• filters – dictionary of ldap query

Returns:

query result list

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> ret = query_ldap(bind, 'dc=foo,dc=bar', ['sn', 'givenName'], objectClass='person', samAccountName='person1')
>>> print(ret)

vmam.check_ldap_version(bind_object)

Determines the LDAP version

Parameters:bind_object – LDAP bind object Returns:LDAP version code: MS-LDAP or N-LDAP or LDAP

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> ret = check_ldap_version(bind)
>>> print(ret)

vmam.new_user(bind_object, username, **attributes)

Create a new LDAP user

Parameters:

• bind_object – LDAP bind object
• username – distinguishedName of user
• attributes – Dictionary attributes

Returns:

LDAP operation result

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> new_user(bind, 'CN=ex_user1,OU=User_ex,DC=foo,DC=bar', objectClass='user', givenName='User 1', sn='Example')

vmam.set_user(bind_object, username, **attributes)

Modify an exists LDAP user

Parameters:

• bind_object – LDAP bind object
• username – distinguishedName of user
• attributes – Dictionary attributes

Returns:

LDAP operation result

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> set_user(bind, 'CN=ex_user1,OU=User_ex,DC=foo,DC=bar', givenName='User 1', sn='Example')

vmam.delete_user(bind_object, username)

Modify an exists LDAP user

Parameters:

• bind_object – LDAP bind object
• username – distinguishedName of user

Returns:

LDAP operation result

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> delete_user(bind, 'CN=ex_user1,OU=User_ex,DC=foo,DC=bar')

vmam.set_user_password(bind_object, username, password, *, ldap_version='LDAP')

Set password to LDAP user

Parameters:

• bind_object – LDAP bind object
• username – distinguishedName of user
• password – password to set of user
• ldap_version – LDAP version (LDAP or MS-LDAP)

Returns:

None

>>> conn = connect_ldap('dc1.foo.bar')
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> new_user(bind, 'CN=ex_user1,OU=User_ex,DC=foo,DC=bar', givenName='User 1', sn='Example')
>>> set_user_password(bind, 'CN=ex_user1,OU=User_ex,DC=foo,DC=bar', 'password', ldap_version='MS-LDAP')
>>> set_user(bind, 'CN=ex_user1,CN=Users,DC=office,DC=bol', pwdLastSet=-1, userAccountControl=66048)

vmam.add_to_group(bind_object, groupname, members)

Add a member of exists LDAP group

Parameters:

• bind_object – LDAP bind object
• groupname – distinguishedName of group
• members – List of a new members

Returns:

LDAP operation result

>>> conn = connect_ldap('dc1.foo.bar')
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> add_to_group(bind, 'CN=ex_group1,OU=Groups,DC=foo,DC=bar', 'CN=ex_user1,CN=Users,DC=office,DC=bol')

vmam.remove_to_group(bind_object, groupname, members)

Remove a member of exists LDAP group

Parameters:

• bind_object – LDAP bind object
• groupname – distinguishedName of group
• members – List of a removed members

Returns:

LDAP operation result

>>> conn = connect_ldap('dc1.foo.bar')
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> remove_to_group(bind, 'CN=ex_group1,OU=Groups,DC=foo,DC=bar', 'CN=ex_user1,CN=Users,DC=office,DC=bol')

vmam.filetime_to_datetime(filetime)

Convert MS filetime LDAP to datetime

Parameters:filetime – filetime number (nanoseconds) Returns:datetime object

>>> dt = filetime_to_datetime(132130209369676516)
>>> print(dt)

vmam.datetime_to_filetime(date_time)

Convert datetime to LDAP MS filetime

Parameters:date_time – datetime object Returns:filetime number

>>> ft = datetime_to_filetime(datetime.datetime(2001, 1, 1))
>>> print(ft)

vmam.get_time_sync(timedelta)

It takes the date for synchronization

Parameters:timedelta – Time difference to subtract (string: 1s, 2m, 3h, 4d, 5w) Returns:datetime object

>>> td = get_time_sync('1d')
>>> print(td)

vmam.string_to_datetime(string)

Convert string date to datetime

Parameters:string – Datetime in string format (‘dd/mm/yyyy’ or ‘mm/dd/yyyy’) Returns:Datetime object

>>> dt = string_to_datetime('28/2/2019')
>>> print(dt)

vmam.format_mac(mac_address, mac_format='none')

Format mac-address with the specified format

Parameters:

• mac_address – mac-address in any format
• mac_format –

  mac format are (default=none):

  none 112233445566

  hypen 11-22-33-44-55-66

  colon 11:22:33:44:55:66

  dot 1122.3344.5566

Returns:

mac-address with the specified format

>>> m = format_mac('1A2b3c4D5E6F', 'dot')
>>> print(m)

vmam.connect_client(client, user, password)

Connect to client with WINRM protocol

Parameters:

• client – hostname or ip address
• user – username used for connection on client
• password – password of user

Returns:

WINRM protocol object

>>> cl = connect_client('host1', r'domain\user', 'password')
>>> print(cl)

vmam.run_command(protocol, command)

Run command to a WINRM client

Parameters:

• protocol – WINRM protocol object
• command – command to run on client

Returns:

Output of command

>>> cl = connect_client('host1', r'domain\user', 'password')
>>> cmd = run_command(cl, 'ipconfig /all')
>>> print(cmd)

vmam.get_mac_address(protocol, *exclude)

Get mac-addresses to remote client

Parameters:protocol – WINRM protocol object Returns:list mac-address

>>> cl = connect_client('host1', r'domain\user', 'password')
>>> m = get_mac_address(cl)
>>> print(m)

vmam.get_client_user(protocol)

Get the last user who logged in to the machine

Parameters:protocol – WINRM protocol object Returns:user string

>>> cl = connect_client('host1', r'domain\user', 'password')
>>> u = get_client_user(cl)
>>> print(u)

vmam.check_vlan_attributes(value, method='like', *attributes)

Check VLAN attributes with like or match method

Parameters:

• value – value to check
• method – ‘like’ or ‘match’
• attributes – list of attributes

Returns:

boolean

>>> conn = connect_ldap(['dc1.foo.bar'])
>>> bind = bind_ldap(conn, r'domain\user', 'password', tls=True)
>>> user = query_ldap(bind, 'dc=foo,dc=bar', ['memberof', 'description', 'department'],
                     objectClass='person', samAccountName='person1')
>>> ok = check_vlan_attributes('business', user[0].get('attributes').get('description'))
>>> print(ok)

vmam.get_mac_from_file(path, mac_format='none')

Get mac-address from file list

Parameters:

• path –

  Path of file list. Mac-address can write in any format.

  file example (/tmp/list.txt):

  112233445566

  # mac of my Linux

  11-22-33-44-55-66

  # this macs is

  # other pc of my office

  11:22:33:44:55:66

  1122.3344.5566

• mac_format –

  mac format are (default=none):

  none 112233445566

  hypen 11-22-33-44-55-66

  colon 11:22:33:44:55:66

  dot 1122.3344.5566

Returns:

list

>>> get_mac_from_file('/tmp/list')

vmam.timestamp_to_datetime(timestamp)

Convert LDAP Kerberos timestamp LDAP to datetime

Parameters:timestamp – kerberos timestamp string Returns:datetime object

>>> dt = timestamp_to_datetime('20200903053604Z')
>>> print(dt)

vmam.datetime_to_timestamp(date_time)

Convert datetime to LDAP Kerberos timestamp

Parameters:date_time – datetime object Returns:kerberos timestamp string

>>> ft = datetime_to_timestamp(datetime.datetime(1986, 1, 25))
>>> print(ft)