Here's a walk-through of how to use Shared Credentials, as of version 0.5.1 of the gem.
In order to keep verbosity to a minimum, all of the examples assume that the Nexpose module has been included:
As with all uses of the gem, in order to interact with a Nexpose console you will need an active, valid connection. The following line can be assumed for all code below:
nsc = Connection.new('10.2.0.1', 'nxadmin', 'secret-password') nsc.login
List All Current Shared Credentials
This will get an Array of all existing credentials. This is just a summary of each credential
Modify the Configuration of an Existing Credential
Load in the configuration details of a credential. This can be used to modify the existing cred.
Note that when password information has already been saved, it is not transferred as part of this request. If the credential is saved without password details, they will be preserved on the console. You should only set password information if it is changing.
Here we add site 42 to the list of sites this shared credential is applied to.
cred = SharedCredential.load(nsc, 13) cred.sites << 42 cred.save(nsc)
Create a New Shared Credential
Here we create a new shared credential from scratch. It's an SSH credential with SUDO privilege escalation. Note that saving of a SharedCredential does not return the assigned ID (as do most save methods in the gem); you will need to list the shared credentials to get it.
cred = SharedCredential.new('SSH-SUDO nxscan') cred.type = Credential::Type::SSH cred.privilege_type = Credential::ElevationType::SUDO cred.privilege_username = 'nxscan' cred.privilege_password = 'open$esam3' cred.sites << 142 cred.save(nsc)
Disable a Shared Credential for Sites
Through the web interface, shared credentials can be assigned to all sites or a limited set of sites through the Administration page. But you also have the ability to disable a shared credential at the site level. The gem exposes this functionality through the SharedCredential (not the Site).
cred = SharedCredential.load(nsc, 13) cred.disabled << 142 cred.save(nsc)
This functionality could be used to temporarily disable the credential on all sites, for example if it is known that an account is temporarily locked out. Turning it back on is just a matter of clearing the disabled list.
# Disable this credential on all sites. cred = SharedCredential.load(nsc, 13) cred.disabled = cred.sites cred.save(nsc) # Re-enable it for all assigned sites. cred.disabled.clear cred.save(nsc)
A copy of this is also maintained on the gem wiki: https://github.com/rapid7/nexpose-client/wiki/Using-Shared-Credentials