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:

include Nexpose  

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

nsc.shared_credentials  

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