Module: userid

Inheritance diagram

Class Reference

User-ID and Dynamic Address Group updates using the User-ID API

class panos.userid.UserId(device, prefix='', ignore_dup_errors=True)

User-ID Subsystem of Firewall

A member of a firewall.Firewall object that has special methods for interacting with the User-ID API. This includes login/logout of a user, user/group mappings, and dynamic address group tags.

This class is typically not instantiated by anything but the base.PanDevice class itself. There is an instance of this UserId class inside every instantiated base.PanDevice class.

Support: UserId API is supported on Panorama starting with Panorama 8.0

UserId API is supported on all firewall PAN-OS versions but with varying features as noted in the documentation for each method.

Parameters:

• device (base.PanDevice) – The firewall or Panorama this user-id subsystem leverages
• prefix (str) – Prefix to use in all IP tag operations for Dynamic Address Groups
• ignore_dup_errors (bool) – Devices produce errors when a tag is registered that already exists. Set to true to ignore these errors. (Default: True)

audit_registered_ip(ip_tags_pairs, timeout=None)

Synchronize the current registered-ip tag list to this exact set of ip-tags

Sets the registered-ip tag list on the device. Regardless of the current state of the registered-ip tag list when this method is called, at the end of the method the list will contain only the ip-tags passed in the argument. The current state of the list is retrieved to reduce the number of operations needed. If the list is currently in the requested state, no API call is made after retrieving the list.

Support: PAN-OS 6.0 and higher

Warning

This will clear any batch without it being sent, and can’t be used as part of a batch.

Parameters:

• ip_tags_pairs (dict) – dictionary where keys are ip addresses and values or tuples of tags
• timeout (string) – The optional timeout value in seconds.

audit_registered_ip_for_tag(tag, ip_addresses, timeout=None)

Synchronize the current registered-ip tag to tag only the specificied IP addresses.

Sets the registered-ip list for a single tag on the device. Regardless of the current state of the registered-ip tag list when this method is called, at the end of the method the list for the specified tag will contain only the ip addresses passed in the argument. The current state of the list is retrieved to reduce the number of operations needed. If the list for this tag is currently in the requested state, no API call is made after retrieving the list.

Support: PAN-OS 6.0 and higher

Warning: This will clear any batch without it being sent, and can’t be

used as part of a batch.

Parameters:

• tag (string) – Tag to audit
• ip_addresses (list) – List of IP addresses that should have the tag
• timeout (string) – The optional timeout value in seconds.

batch_end()

End a batched API call and send it to the firewall

This method usually follows a batch_start() and several other operations.

The API call will not be sent to the firewall until batch_end() is called. This allows multiple operations to be added to a single API call.

batch_start()

Start creating an API call

The API call will not be sent to the firewall until batch_end() is called. This allows multiple operations to be added to a single API call.

clear_registered_ip(ip=None, tags=None, prefix=None)

Unregister registered/tagged addresses

Removes registered addresses used by dynamic address groups. When called without arguments, removes all registered addresses

Note: Passing a single ip and/or single tag to this method results in a response from the firewall that contains only the relevant entries. ie. the filtering is done on the firewall before it responds. Passing a list of multiple ip addresses or tags will result in retreival of the entire tag database from the firewall which is then filtered and returned with only the relevant entries. Therefor, using a single ip or tag is more efficient.

Support: PAN-OS 6.0 and higher

Warning

This will clear any batch without it being sent, and can’t be used as part of a batch.

Parameters:

• ip (list or str) – IP address(es) to remove tags for
• tags (list or str) – Tag(s) to remove
• prefix (str) – Override class tag prefix

get_group_members(group)

Returns a list of users in the given group.

Parameters:group – The name of the group. Returns:list

get_groups(style=None)

Get a list of groups.

Parameters:style – The type of groups to retrieve. If unspecified, returns a list of all groups. Can be “custom-group”, “dynamic”, or “xmlapi”. Returns:list

get_registered_ip(ip=None, tags=None, prefix=None)

Return registered/tagged addresses

When called without arguments, retrieves all registered addresses.

Note: Passing a single ip and/or single tag to this method results in a response from the firewall that contains only the relevant entries. ie. the filtering is done on the firewall before it responds. Passing a list of multiple ip addresses or tags will result in retreival of the entire tag database from the firewall which is then filtered and returned with only the relevant entries. Therefor, using a single ip or tag is more efficient.

Support: PAN-OS 6.0 and higher

Parameters:

• ip (list or str) – IP address(es) to get tags for
• tags (list or str) – Tag(s) to get
• prefix (str) – Override class tag prefix

Returns:

ip addresses as keys with tags as values

Return type:

dict

Raises:

PanDeviceError if running PAN-OS < 8.0 and a logfile is returned – instead of IP/tag mapings.

get_user_tags(user=None, prefix=None)

Get the dynamic user tags.

Note: PAN-OS 9.1+

Parameters:

• user – Get only this user’s tags, not all users and all tags.
• prefix – Override class tag prefix.

Returns:

Dict where the user is the key and the value is a list of tags.

Return type:

dict

login(user, ip, timeout=None)

Login a single user

Maps a user to an IP address

This method can be batched with batch_start() and batch_end().

Parameters:

• user (str) – a username
• ip (str) – an ip address
• timeout (int) – timeout in minutes to remove this mapping

logins(users)

Login multiple users in the same API call

This method can be batched with batch_start() and batch_end().

Parameters:users – a list of sets of user/ip mappings with optional timeout in minutes eg. [(‘user1’, ‘10.0.1.1’), (‘user2’, ‘10.0.1.2’, 60)]

logout(user, ip)

Logout a single user

Removes a mapping of a user to an IP address

This method can be batched with batch_start() and batch_end().

Parameters:

• user (str) – a username
• ip (str) – an ip address

logouts(users)

Logout multiple users in the same API call

This method can be batched with batch_start() and batch_end().

Parameters:users – a list of sets of user/ip mappings eg. [(user1, 10.0.1.1), (user2, 10.0.1.2)]

register(ip, tags, timeout=None)

Register an ip tag for a Dynamic Address Group.

This method can be batched with batch_start() and batch_end().

Parameters:

• ip (list or str) – IP address(es) to tag
• tags (list or str) – The tag(s) for the IP address
• timeout (string) – The optional timeout value in seconds. (Max is 2,592,000 sec (30 days))

send(uidmessage)

Send a uidmessage to the User-ID API of a firewall

Used for adhoc User-ID API calls that are not supported by other methods in this class. This method cannot be batched.

Parameters:uidmessage (str) – The UID Message in XML to send to the firewall

set_group(group, users)

Set a group’s membership to the specified users.

This method can be batched with batch_start() and batch_end().

Parameters:

• group – The group name.
• users (list) – The users to be in this group.

tag_user(user, tags, timeout=None, prefix=None)

Tags the user with the specified tags.

This method can be batched with batch_start() and batch_end().

Note: PAN-OS 9.1+

Parameters:

• user – The user.
• tags (list) – The list of tags to apply.
• timeout (int) – (Optional) The timeout for the given tags.
• prefix – Override class tag prefix.

unregister(ip, tags)

Unregister an ip tag for a Dynamic Address Group

This method can be batched with batch_start() and batch_end().

Parameters:

• ip (list or str) – IP address(es) with the tag to remove
• tags (list or str) – The tag(s) to remove from the IP address

untag_user(user, tags=None, prefix=None)

Removes tags associated with a user.

This method can be batched with batch_start() and batch_end().

Note: PAN-OS 9.1+

Parameters:

• user – The user.
• tags (list) – (Optional) Remove only these tags instead of all tags.
• prefix – Override class tag prefix.