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)[source]
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)[source]
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)[source]
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()[source]
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()[source]
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)[source]
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
orstr
) – IP address(es) to remove tags fortags (
list
orstr
) – Tag(s) to removeprefix (str) – Override class tag prefix
- get_group_members(group)[source]
Returns a list of users in the given group.
- Parameters:
group – The name of the group.
- Returns:
list
- get_groups(style=None)[source]
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)[source]
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
orstr
) – IP address(es) to get tags fortags (
list
orstr
) – Tag(s) to getprefix (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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
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)[source]
Register an ip tag for a Dynamic Address Group.
This method can be batched with batch_start() and batch_end().
- Parameters:
ip (
list
orstr
) – IP address(es) to tagtags (
list
orstr
) – The tag(s) for the IP addresstimeout (string) – The optional timeout value in seconds. (Max is 2,592,000 sec (30 days))
- send(uidmessage)[source]
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)[source]
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)[source]
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)[source]
Unregister an ip tag for a Dynamic Address Group
This method can be batched with batch_start() and batch_end().
- Parameters:
ip (
list
orstr
) – IP address(es) with the tag to removetags (
list
orstr
) – The tag(s) to remove from the IP address
- untag_user(user, tags=None, prefix=None)[source]
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.