Skip to main content

User-defined functions

In order for agtdos , agttelnet , or agtssh to perform an agent operation, you must implement the corresponding function in your script. Write these functions to provide interaction details between Bravura Security Fabric and the target.

The agents use the following functions:

  • list( const $wantGroups, const $wantAttributes) Lists accounts on the target system, and the attributes for each account.

    The parameters passed to the function are as follows:

    • $wantGroups – determines if this function should retrieve group membership.

      If the value of $wantGroups is a non-zero value, write your function to retrieve the group(s) to which each account belongs while listing accounts.

    • $wantAttributes – determines if this function should retrieve attributes for each account.

      If the value of $wantAttributes is a non-zero value, write your function to list the attributes for each account.

    If both $wantGroups and $wantAttributes are 0 , write your function to list accounts on the target system only.

    See listmembermethod below for more information about listing group membership.

  • listgroups( const $wantMembers) Lists groups.

    The parameters passed to the function are as follows:

    • $wantMembers – determines if this function should retrieve group membership.

      If the value of $wantMembers is non-zero, write your function to retrieve the account(s) that belong to each group while listing groups.

      If this value of $wantMembers is 0, write your function to list groups only.

    See listmembermethod below for more information about listing group membership.

  • listresource( const $resourceType) Lists resources for Bravura Privilege ’s infrastructure auto discovery feature. The parameters passed to the function are as follows:

    • $resourceType defines which type of resource to list.

      Depending on target system configuration, listresource() will be called multiple times each with a different resourceType value. The values that resourceType can take on are:

      • ls_compsvr – list server computer objects.

      • ls_admmember – list members of administrative groups.

      • ls_taskacct – list scheduled task accounts.

      • ls_comacct – list COM object accounts.

      • ls_iisacct – list IIS virtual directory accounts.

      • ls_scmacct – list Service Control Manager accounts.

  • movecontext( const $info ) Moves an account to a new context or location on a context-sensitive target. Supported in Bravura Identity and Bravura Privilege .

  • isenabled( const $info ) Checks if an account is enabled. Supported in Bravura Pass and Bravura Privilege .

  • islocked( const $info ) Checks if an account is locked. Supported in Bravura Pass and Bravura Privilege .

  • ispwexpired( const $info ) Checks if an account’s password is expired. Supported in Bravura Pass and Bravura Privilege .

  • isacctexpired( const $info ) Checks if an account is expired. Supported in Bravura Pass and Bravura Privilege .

  • disable( const $info ) Disables an account. Supported in Bravura Identity and Bravura Privilege .

    Most systems differentiate between disabled and intruder-locked accounts.

  • enable( const $info ) Enables an account. Supported in Bravura Identity and Bravura Privilege .

  • lock( const $info ) Locks an account (sets the intruder lockout). Supported in Bravura Pass and Bravura Privilege .

    Most system differentiate between intruder-locked and disabled accounts.

  • unlock( const $info ) Unlocks an account (clears the intruder lockout). Supported in Bravura Pass and Bravura Privilege .

  • expirepw( const $info ) Expires an account’s password. Supported in Bravura Pass and Bravura Privilege .

  • unexpirepw( const $info ) Unexpires an account’s password. Supported in Bravura Pass and Bravura Privilege .

  • expireacct( const $info ) Expires an account. Supported in Bravura Pass and Bravura Privilege .

  • unexpireacct( const $info ) Unexpires an account. Supported in Bravura Pass and Bravura Privilege .

  • create( const $info ) Creates a new account on the target system. This operation creates the account (possibly using a template for some attribute values), then sets other attribute values – including the password for the new account. Supported in Bravura Identity and Bravura Privilege .

    This function should make use of the target system administrator credentials.

  • delete( const $info ) Deletes an existing account on the target system. The typical behavior is to first ensure that the account being deleted exists. Supported in Bravura Identity and Bravura Privilege .

    You may also wish to include instructions to delete any files or objects associated with the account.

  • verify( const $info ) Checks if a given password is the correct, current password for an account. If the application supports the concept of intruder lockout and the verification fails, the intruder lockout counter is incremented. Supported in Bravura Identity and Bravura Privilege .

  • admin_verify( const $info ) Checks if a given password is the correct, current password for an account without triggering an intruder lockout if the password is not correct. Supported in Bravura Pass and Bravura Privilege .

  • verifyreset( const $info ) Verifies if the account’s password matches the new password, and if the verification fails, administratively sets it to the new password. If the verification succeeds, then the reset is not necessary, and the operation returns success. Supported in Bravura Pass and Bravura Privilege .

  • reset( const $info ) Administratively resets an account’s password to a new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application. Disabled accounts will remain disabled. Supported in Bravura Pass and Bravura Privilege .

  • change( const $info ) Changes the password for an account, from a known current value to a desired new value. If the application supports the concept of intruder lockout, then the intruder lockout counter is cleared and the account unlocked. If the application supports the concept of password expiry, then the expiry date is set according to the expiry policy of the application. Supported in Bravura Pass and Bravura Privilege .

  • resetexpirepw( const $info ) Administratively resets an account’s password to a new value and expires the account’s new password, so that the user is forced to change his password the next time he logs in. Supported in Bravura Pass and Bravura Privilege .

  • groupuseradd( const $info ) Adds an account to a group. Supported in Bravura Identity and Bravura Privilege .

  • groupuserdelete( const $info ) Removes an account from a group. Supported in Bravura Identity and Bravura Privilege .

  • groupgroupadd( const $info ) Adds a group to a group. Supported in Bravura Identity and Bravura Privilege .

  • groupgroupdelete( const $info ) Removes a group from a group. Supported in Bravura Identity and Bravura Privilege .

  • update( const $info ) Updates attributes for an existing account. Supported in Bravura Identity and Bravura Privilege .

  • userattributes( const $info ) Lists attributes for a specified account. Supported in Bravura Identity and Bravura Privilege .

All functions are optional. To indicate success your function must return 0. To indicate failure, your function must return 1.

Warning

Functions which reset or verify passwords in scripts used by Bravura Privilege for password randomization must always report the result of the reset or verification accurately. Inaccurate status information may result in checked out passwords not working; additionally, if the credential used to manage the target system is being randomized, Bravura Privilege may invalidate its own managed system credential when an erroneous status is returned. Do not assume scripted password changes are always successful; always check return codes.

If your target does not support a particular operation (for example, if there is no intruder lockout mechanism), then omit the corresponding function from the script. If the agent cannot find a particular function in the script, the agent returns a message saying "Function [<operation>] not found in script".

The following additional functions (optional) do not represent actual agent operations, however they are also called directly by the agent:

  • connecttarget( const $cinfo ) called before the first operation is performed.

    This function must return 0 on success, or 1 on failure.

  • disconnecttarget( const $cinfo ) called after the last operation is performed.

    This function must return 0 on success, or 1 on failure.

  • listmembermethod() used to determine the supported method for listing group membership on the target system.

    If both methods are supported, select the method that is the most efficient. This function must return:

    • 0 - if the script cannot list group membership

    • 1 - if the script list accounts in a group while listing groups

    • 2 - if the script lists groups while listing accounts

    The calling program uses the result of listmembermethod, along with your target-configuration settings, to determine the value of $wantGroups and $wantMembers.

    For example, if the calling program is executed with the option to list group membership, and the result of listmembermethod is 1, the calling program executes the function: listgroups(1)

  • addressattrs () used to extend the address wizard by adding additional address line elements. It is only possible to add new address line elements, not remove or change existing ones. This is useful when creating a scripted target system with a scripted platform definition file.

    • If not defined, the address wizard behaves as normal.

    • From within this function the addAddressElement callback function adds a single address line element. The callback function can be called multiple times and takes the following form:

      addAddressElement(name, type, defaultValue, isRequired,restrictedValuesList, description, advanced);

      Where:

      • name: is the string name of the of the address line component.

      • type: is one of ($AddressTypeInt $AddressTypeString $AddressTypeBoolean $AddressTypeKvgroup $AddressTypeRestricted $AddressTypeScript $AddressTypeDir $AddressTypeFile).

      • defaultValue: string default value or empty if no default value.

      • isRequired: boolean, where 1=required and 0=optional.

      • restrictedValuesList: array of display/actual values for each restricted value.

      • description: Textual description of the element.

      • advanced: boolean, 1=display attribute in advanced section and 0=default

    An example is included in the sample agttelnet-racf.psl.

The following function is available to agtssh:

  • credentialoverride(inout $cinfo ) called before all other functions and used to override the adminid and adminpw credentials on the connection to the SSH target.

    • The function is optional, and is not called if it is not defined.

    • The function is called before all other functions.

    • The adminid, adminpw, host, and address elements are readable in the function.

    • The adminid and adminpw elements are settable within the credentialoverride function to other values. The return value for the function does not affect the commitment of the override values - agtssh always uses the returned values for adminid and adminpw for the connection.

    • The host, address, sysid, and syspw elements do not commit overridden values.

    • The adminid and adminpw elements are accessible via a transitional variable to other functions.

    • The variable $COMMON_SHELL can be set in the function to specify a custom shell.

Input parameters ($cinfo and $info)

The connecttarget() and disconnecttarget() functions each take one parameter, an associative array ($cinfo). Each element is a string. Elements of the array are:

  • address the target address.

  • adminid the target system administrator’s ID.

  • adminpw the target system administrator’s password.

  • sysid the target system administrator’s ID if the Is this an additional system password? checkbox is selected.

  • syspw the target system administrator’s password if the Is this an additional system password? checkbox is selected.

Most of the functions that relate to Bravura Security Fabric operations (for example, create(), enable(),reset(), change() ) also take one parameter, an associative array ($info). Each element is a string unless otherwise indicated. Elements of the array are:

  • userid the profile ID of the user.

  • shortid the short ID of the user.

  • fullname the full name of the user.

  • acctid the ID for the account that the user has on this system.

  • newpw the new password (for password reset and create operations).

  • oldpw the old password (for verify operations).

  • modeluid the template ID (for create operations).

  • groupid the group ID (for group* operations).

  • groupname the group description (for group* operations).

  • attributes a KVGroup containing information about attributes to set (for create and update operations)

    The general format of the KVGroup is as follows:

    "attributes" "" = {
  "DEFAULT-ACTION" = "COPY"
  "attribute" "givenName" = {
    "SEQUENCE" = "0"
    "GROUP"    = "0"
    "ACTION"   = "VALUE"
    "VALUE"    = "John"
   }
  "attribute" "sn" = {
    "SEQUENCE" = "0"
    "GROUP"    = "0"
    "ACTION"   = "VALUE"
    "VALUE"    = "Doe"
   }
 }

  • ConnectionCredential a KVGroup containing information about target administrator credentials and system credentials (for reset operations).

    The general format of the KVGroup is as follows:

    "ConnectionCredential" "" = {
  "AdminCredential" "" = {
    "admin1" = "{AES}@KK|dE]=GqX=zqJyTIgqL]XCyECV?AsAJ[O?vBJGpAaEGgfK"
    "admin2" = "{AES}e[LkiHEv?=iAGTD|ZA^cKCYJCb?[tByFDp_=e]EhWDkgHzmD"
   }
  "SysCredential" "" = {
    "sysadm1" = "{AES}fN=>rLOB?^gDICJfc@fYLB@@COGlv=H@IFc@EW?XBJTwFEXB"
   }
 }

Return codes

The return codes for user-defined functions (with the exception of listmembermethod()) for agtdos , agttelnet , and agtssh are as follows:

Code

Value

Description

ACSuccess

0

The operation was successful.

ACUnknownError

1

The operation failed with an unknown error.

ACOperationNotSupported

2

The operation is not supported by the target system.

ACNotConnected

3

Can be used in the connecttarget() function if a connection could not be established.

ACAlreadyConnected

4

Can be used in the connecttarget() function if an attempt is made to connect to a target that already has a connection.

ACInvalidServer

5

Can be used in the connecttarget() function if the target address is invalid.

ACObjectAlreadyExists

6

The object to create (for example, user or group) already exists.

ACInvalidUser

7

The user account is invalid or does not exist.

ACInvalidModelUser

8

The template account is invalid or does not exist.

ACUserNotInGroup

9

The user is not in the specified group.

ACTimeout

10

The operation timed out.

ACAccessDenied

11

The target system administrator could not logon due to a bad ID/password pair, account restrictions, and so on.

ACInvalidGroup

12

The group is invalid or does not exist.

ACUserAlreadyGroupMember

13

The user is already a member of the specified group.

ACVerifyFailed

14

The password could not be verified. Use this code ONLY when the specified password is not correct.

ACInitFailed

15

The operation failed to initialize.

ACLockFailed

16

The operation failed to get a lock on a file while reading or writing.

ACScriptError

17

The operation encountered an error in the script.

ACNotLicensed

18

The operation is not licensed.

ACLogFileFailure

19

Failed to write to the log file.

ACImplementerFailure

20

The implementor failed to perform the operation.

ACAdminLocked

21

The target system administrator account is locked.

ACInvalidPasswd

22

The password is invalid.

ACDelayLoadError

23

The operation encountered an error loading a dll or function point.

ACReadOnlyResource

24

The operation could not write to a resource because it was read only.

ACPluginAborted

25

The plugin failed.

ACPasswordLocked

26

The password is locked.

ACPasswordExpired

27

The password has expired.

ACAccountExpired

28

The account has expired.

ACAccountDisabled

29

The account is disabled.

ACOperationRolledback

30

The operation was rolled back.

ACOperationAborted

31

The operation was aborted.

ACOperationRollbackFailed

32

The rollback operation has failed.

ACEndOfFile

33

The operation has reached the end of file.

ACGroupAlreadyGroupMember

34

The group is already a group member.

ACGroupNotInGroup

35

Group is not a member of group.

ACNull

0xffff

A null code.

In this section: