CiscoISE is a Ruby wrapper for the Cisco Identity Services Engine (ISE) API. This implementation wraps all APIs for ISE 1.1.
Install the library using rubygems
$ gem install cisco-ise
You can then use it in your Ruby scripts with
require 'cisco-ise'
For each MnT that you need to communicate with, you will need to create a CiscoISE::HttpSession:
ise_session = CiscoISE::HttpSession.new("device-name","myusername","mypassword")
To disable SSL support for the HTTP session:
ise_session = CiscoISE::HttpSession.new("device-name","myusername","mypassword", CiscoISE::HttpSession::SSL_DISABLED)
To enable certificate validation for the HTTP session:
ise_session = CiscoISE::HttpSession.new("device-name","myusername","mypassword", CiscoISE::HttpSession::SSL_ENABLED, CiscoISE::HttpSession::CERT_VERIFY_ENABLED)
The following sections refer to the Session Management APIs. Refer to www.cisco.com/en/US/docs/security/ise/1.1/api_ref_guide/ise_api_ref_ch2.html
To return the current Active Session count:
count = CiscoISE::ActiveCountApi.new(ise_session).count
=> "10"
To return the current Posture Session count:
count = CiscoISE::PostureCountApi.new(ise_session).count
=> "12"
To return the current Profiler Session count:
count = CiscoISE::ProfilerCountApi.new(ise_session).count
=> "8"
Firstly create an Active List query
active = CiscoISE::ActiveListApi.new(ise_session)
Next we can iterate through each active session. Each returned object is a CiscoISE::ActiveSession.
active.each do |record| puts record.user_name end
Firstly create an Authenticated Session List query. The default query lists all currently active authenticated sessions.
active = CiscoISE::AuthListApi.new(ise_session)
Next we can iterate through each authenticated session. Each returned object is a CiscoISE::ActiveSession.
active.each do |record| puts record.user_name end
To limit the authenticated session list to authentications starting BEFORE a specific time:
active = CiscoISE::AuthListApi.new(ise_session, '2010-12-14 15:33:15')
To limit the authenticated session list to authentications starting AFTER a specific time:
active = CiscoISE::AuthListApi.new(ise_session, '', '2010-12-14 15:33:15')
To limit the authenticated session list to authentications starting BETWEEN a specific time range:
active = CiscoISE::AuthListApi.new(ise_session, '2010-12-13 15:33:15', '2010-12-14 15:33:15')
Firstly create a MAC Address query.
session = CiscoISE::MacAddressApi.new(ise_session,'00:17:89:01:23:45')
Next we can iterate through each session object. Each returned object is a CiscoISE::SessionParameters.
session.each do |record| puts record.user_name + ":" + record.nas_ip_address end
Firstly create a User Name query.
session = CiscoISE::UserNameApi.new(ise_session,'the-users-name')
Next we can iterate through each session object. Each returned object is a CiscoISE::SessionParameters.
session.each do |record| puts record.user_name + ":" + record.nas_ip_address end
Firstly create a NAS IP Address query.
session = CiscoISE::NasIpAddressApi.new(ise_session,'1.1.1.1')
Next we can iterate through each session object. Each returned object is a CiscoISE::SessionParameters.
session.each do |record| puts record.user_name + ":" + record.nas_ip_address end
Firstly create an Endpoint IP Address query.
session = CiscoISE::EndPointIpAddressApi.new(ise_session,'10.10.10.10')
Next we can iterate through each session object. Each returned object is a CiscoISE::SessionParameters.
session.each do |record| puts record.user_name + ":" + record.nas_ip_address end
Please note that this feature is documented as “manually delete inactive sessions”. Do not use this on live session. To disconnect/delete a live session please use the CoA api.
Firstly create a new Delete session.
delete = CiscoISE::DeleteApi.new(ise_session)
There are three different methods that can be used to delete sessions. To delete all sessions:
delete.all
To delete a session based on a MAC Address:
delete.mac_address('00:17:89:01:23:45')
To delete a session based on a session ID:
delete.session_id('1234567890987654321')
The following sections refer to the Troubleshooting APIs. Refer to www.cisco.com/en/US/docs/security/ise/1.1/api_ref_guide/ise_api_ref_ch3.html
To return a product object that contains details on the MnT:
product = CiscoISE::VersionApi.new(ise_session).product puts product.name puts product.type_of_node puts product.version puts product.type_of_node_as_code
To return a list of Failure Reasons:
failure = CiscoISE::FailureReasonsApi.new(ise_session)
To retrieve a specific code:
code = failure.find_code('86023') puts code.failure_id + ':' + code.cause
To iterate through each failure code:
failure.each do |code| puts code.id + code.cause end
To return a list of CiscoISE::AuthStatusElements for a given MAC Address. By default this query returns records that occurred in the last 10 days (864000 seconds) and limits the records to 200.
auth = CiscoISE::AuthStatusApi.new(ise_session, '00:17:89:01:23:45')
To limit the results to events in the last hour (60 seconds x 60 minutes = 3600 seconds) and limit the records to 100:
auth = CiscoISE::AuthStatusApi.new(ise_session, '00:17:89:01:23:45',3600,100)
To iterate through each element:
auth.each do |element| puts "doing something with " + element.username end
To return a list of CiscoISE::AcctStatusElements for a given MAC Address
acct = CiscoISE::AcctStatusApi.new(ise_session, '00:17:89:01:23:45', 20000)
To limit search results to sessions that occurred within the last 60 minutes (60 seconds * 60 minutes = 3600 seconds):
acct = CiscoISE::AcctStatusApi.new(ise_session, '00:17:89:01:23:45', 3600)
To iterate through each element:
acct.each do |element| puts element.calling_station_id + ':' + element.paks_in end
The following sections refer to the CoA APIs. Refer to www.cisco.com/en/US/docs/security/ise/1.1/api_ref_guide/ise_api_ref_ch4.html
Before forcing a reauth, you need to locate an ActiveSession. Once you have the ActiveSession, you can then pass this object to the reauth API.
auth = CiscoISE::AuthListApi.new(ise_session)
active.each do |record|
if record.user_name == 'someuser'
success = CiscoISE::ReauthApi.new(ise_session).rerun(record).success?
end
There are three different reauth methods. Each can be accessed in the following way:
CiscoISE::ReauthApi.new(ise_session).default(record) CiscoISE::ReauthApi.new(ise_session).last(record) CiscoISE::ReauthApi.new(ise_session).rerun(record)
Before issuing a discconnect, you need to locate an ActiveSession. Once you have the ActiveSession, you can then pass this object to the diconnect API.
auth = CiscoISE::AuthListApi.new(ise_session)
active.each do |record|
if record.user_name == 'someuser'
success = CiscoISE::DisconnectApi.new(ise_session).bounce(record).success?
end
There are three different disconnect methods. Each can be accessed in the following way:
CiscoISE::ReauthApi.new(ise_session).default(record) CiscoISE::ReauthApi.new(ise_session).bounce(record) CiscoISE::ReauthApi.new(ise_session).shutdown(record)
-
Check out the latest master to make sure the feature hasn’t been implemented or the bug hasn’t been fixed yet.
-
Check out the issue tracker to make sure someone already hasn’t requested it and/or contributed it.
-
Fork the project.
-
Start a feature/bugfix branch.
-
Commit and push until you are happy with your contribution.
-
Make sure to add tests for it. This is important so I don’t break it in a future version unintentionally.
-
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Copyright © 2012 Mark Sullivan. See LICENSE.txt for further details.