A unofficial library which provides wrappers around IBM Security Secret Server REST APIs. Also compatible with Thycotic Secret Server
ISSS - A Python module for IBM Security Secret Server
isss module is meant to be an abstract layer on top of the IBM Security Secret Server REST APIs.
It is NOT a full implementation of the REST APIs capabilities. It only provides wrappers for most useful scenarios, additionnal functions will appear from time to time.
Also, notice that you will use it at your own risk, as it is not officially supported by IBM
Installation & pre-requisites
From a terminal, simply issue the following command :
$ pip install isss
And that's all ! The library should work as-is. It should be OS independant too, but it's compatible with Python 3.x only
You can verify your installation by copy-pasting this line into a shell :
$ python -c "import isss; print (isss.version)"
It should display your current isss version. If you've got an error complaining about several missing modules, it's probably a system config issue resulting in the old python 2.7 being run by default instead of python 3
Try to issue the same command, but using
python3 instead of
python to force the use of python 3.x
$ python3 -c "import isss; print (isss.version)"
Current known limitations
Many ! Either because I'm lacking of time or because some REST APIs are simply not available (unlike their SOAP counterpart), you might find that the thing you want to achieve is not possible with the current version of the module.
Non exhaustive list of missing features:
- Create or search secret policies (REST APIs seem not available)
- Advanced search (pagination, complex queries). Only per-id or global search text is available for most items (users, secrets, groups, folders) and only first 100 items are returned
- Checkin, checkout
- Recorded sessions
This module is still a work in progress, though.
Importing the module
Before using the module, you must import it (who knew?). The
isss module contains a class named
ISSS which contains everything you need.
from isss import ISSS isss = ISSS("https://your.server.demo.com/SecretServer","admin","yourpassword")
A stub is basically a map of values that you can read, but also edit then push back to secret server to create or update a resource. You'll get a stub (or list of stubs) after a search, a create, or an update.
Tip : from an interactive shell, stubs can be pretty-printed to have a clear view of their content:
>>> u = isss.getUser(3) >>> u <User id='3' username='python' displayName='Python App' /> >>> print(u) - id : 3 - userName : python - displayName : Python App - lastLogin : 2019-06-13T12:30:31 - created : 2019-06-11T09:14:12 - enabled : True - loginFailures : 0 - emailAddress : None - userLcid : 0 - domainId : -1 - lastSessionActivity : None - isLockedOut : False - radiusUserName : None - twoFactor : False - radiusTwoFactor : False - isEmailVerified : False - mustVerifyEmail : False - verifyEmailSentDate : 0001-01-01T00:00:00 - passwordLastChanged : 0001-01-01T00:00:00 - dateOptionId : -1 - timeOptionId : -1 - isEmailCopiedFromAD : False - organizationUnitId : -1 - adGuid : None - adAccountExpires : 0001-01-01T00:00:00 - resetSessionStarted : 0001-01-01T00:00:00 - isApplicationAccount : True - oathTwoFactor : False - oathVerified : False - duoTwoFactor : False - fido2TwoFactor : False - password : None >>>
Tip: The variables inside a stub are case-insensitive.
stub["username"] = "romain" stub["userName"] = "romain" #similar to the previous line
Of course, accessing an unknown variable inside the stub will raise an exception.
Each stub will also have a create(), an update() and a delete() method, in order to be pushed back to Secret Server.
It's now time to read the examples below to have a better understanding of the concept.
Doing some searches
Each time you'll search for something, you'll get a stub if you pass a numerical id, or a list of stubs if you pass a string query.
for s in isss.getSecret("centos root account"): print (s['id'])
or get a specific secret, using a secret ID
for u in isss.getUser("admin"): print (u['id'])
...or get a specific user, using a user ID
Searching groups (and adding users into a group)
for g in isss.getGroup("Users"): print (g['id'])
...or get a specific group, using a group ID
for f in isss.getFolder("Windows Systems"): print (f['id'])
...or get a specific folder, using a folder ID
for t in isss.getTemplate("Unix Account (SSH)") print ("Template id found : "), (t["id"])
...or get a specific template, using a template ID
template = isss.getTemplate(6007)
To create something, you'll need an empty stub of this particular something. Once you've got a stub, edit the stub then call its create() method.
Creating a secret
#To create a new secret, grab a template id first myid = isss.getTemplates("Unix Account (SSH)")["id"] #Then grab the corresponding secret stub #which contains basically all the default values for this template. stub = isss.getSecretStub(myid) #Then edit these values. Be careful, some of them might be mandatory #Typically 'name' which is the secret name #Developer tip : these fields are case insensitive stub["name"] = "python\\foobar.demo.com" stub["machine"] = "foobar.demo.com" stub["username"] = "root" stub["password"] = stub.generatePassword() stub["folderId"] = isss.getFolders("Linux")["id"] stub["enableInheritPermissions"] = False #important for the next sample #Display a nice listing of all the available fields and their current value #This is useful when playing live with the module print (stub) #Then finally create the secret, and keep a reference #We'll need it very soon secret = stub.create()
Pay attention to the use of the generatePassword() method in the previous example.
This method is only available on stub object, because each secret field can have its own secret policy.
This is why you also might need to specify the name of the field as a parameter so that the method will generate a valid password for the associated field.
For convenient reason, default field name is set to
# private key passphrase may require a longer password stub["Private Key Passphrase"] = stub.generatePassword("Private Key Passphrase")
Creating a secret permission
To create a new permission for a specific secret, you must first grab a secret id to retrieve the corresponding stub.
#the secret variable come from the previous sample stub = isss.getSecretPermissionStub(secret["id"]) stub["userId"] = 4 stub["secretAccessRoleName"] = "View" stub.create()
Possible values for secretAccessRoleName are : "Owner", "View", "List", or "Edit"
Creating a folder permission
To create a new permission for a specific folder, you must first grab a folder id to retrieve the corresponding stub.
stub = isss.getFolderPermissionStub(isss.getFolder("Windows")["id"]) stub["userId"] = 4 stub["folderAccessRoleName"] = "View" stub.create()
Possible values for folderAccessRoleName are : "Owner", "View", "List", or "Edit"
Creating a user
To create a new user, it's very similar, yet simpler :
stub = isss.getUserStub() stub["username"] = "lucifer" stub["displayname"] = "Lucifer Morningstar" stub["password"] = "Passw0rd" stub.create()
Creating a group
You should now be familiar with the concept...
stub = isss.getGroupStub() stub["name"] = "awesome people" mygroup = stub.create() #keep a reference to the newly created group
As seen before, once your group is created you can store the result into a variable so you can start adding users
Caution, add() is expecting a numerical userId or a username. Not a search query !
Update works exactly like create, except your stub has already been created, so instead of calling create() you will call... well... update()
Updating a user
u = isss.getUser(4) u["password"] = "new password" u.update()
Updating a secret
s = isss.getSecret(12) s["name"] += " (updated)" s.update()
Updating a group
Group can be updated like any regular stub, but they also have 3 additionals methods.
A method to add a user into the group:
isss.getGroup(2).add("admin") #using a search query - must return only 1 result isss.getGroup(2).add(2) #or a userid isss.getGroup(2).add("admin").add("romain") #tip: you can chain methods
A method to remove a user from the group:
isss.getGroup(2).remove("admin") isss.getGroup(2).remove(2) isss.getGroup(2).remove("admin").remove("romain")
And a method to list current users in the group:
for user in isss.getGroup(2).getUsers(): print user["id"]
Note : for performance reasons, the
getUsers() method returns a list of IDs and usernames, not a list of stubs.
While many things in Secret Server are never really deleted (we should rather say disabled), you can delete object from the server by calling the delete() function on the corresponding stub object
#delete an existing stub myUser.delete() myGroup.delete() #search & delete isss.getSecret("foobar").delete()
For some reasons, Scripts APIs don't seem to be available as REST APIs, although they are available as SOAP APIs. For the sake of simplicity (I didn't want to mess with SOAP), the current implementation scraps the Web UI hence is likely to be broken at some point if you are not using the good version of Secret Server (tested on 10.6.000027 only)
To enable them, you'll need to add
True to the ISSS constructor :
from isss import ISSS isss = ISSS( "https://your.server.demo.com/SecretServer", "admin", "yourpassword", True)
Get all scripts metadata (PowerShell, SSH, SQL)
It's very easy to retrieve the list of available scripts.
#This function only returns script names and IDs #Not the actual scripts content scripts = isss.getScriptList() #Iterate over scripts, and grab & update their content for script in scripts: if script.name == 'Test SSH': script = isss.getScript(script) # get the content script.content += "\n#automatically added by python" script.update()
Of course if you know the id of a script, you can still grab it directly
script = isss.getScript(8) script.content += "\n#automatically addedd by python" script.update()
It worth noting that these scripts are not stub objects, like we have seen before.
OK there is a real need behind the crappy Script API that you've just discovered. I'm not expecting anyone to use it (especially since this API might stop working at some point), but if like me you are tired to edit your Heartbeat or Password Changer scripts from the web UI, you might be interested by this filewatcher command which depends on it.
From your shell, simply issue the following command :
$ isss-fw https://server/SecretServer admin password directorypath
And it will start the filewatcher on the specified
directorypath (which should be empty - the program will prompt you to delete its content if it's not)
If the directory doesn't exist, it will be created, and scripts will be automatically downloaded into it. Then any change to one of these files will be detected by the filewatcher and sent back to ISSS.
Be careful, it doesn't work with vim or any editor which are using temporary files. I'm using brackets.io, which works pretty well for me.
Also, you will quickly discover that (for now at least) you can't pass the current directory "." as the path parameter, so you will need to start the command from outside the directory you want to use.
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.