call-servers

	This program places an API call to multiple servers.  The
servers can be selected with any combination of (partial) server names,
(partial) group names, and/or (partial) group tag names.

	The API calls can be any that start with
/v1/server/{server_id}/.  GET, PUT, POST, and DELETE calls are
supported.  PUT and POST calls require a json body; that's passed to
stdin when running this tool.  The output goes to stdout, with a
"#======== server name" separator between output blocks.


Requirements:
- ruby
- The following ruby gems installed: oauth2, rest-client, json, and
  optparse.  The following command will install all
  optional gems needed by the CloudPasssage API clients:
  sudo gem install oauth2 rest-client json public_suffix ip
- A Read only or Full access API key and secret (*), placed in 
  /etc/halo-api-keys separated by a vertical pipe, like:
aa00bb44|11111111222222223333333344444444
  This file should be owned by the user that runs api scripts, mode 600.
  Developers only: If you're working with an alternate grid, put that 
  grid's api hostname and port in the third column of the line:
aa00bb44|11111111222222223333333344444444|api.example.com:9999

* These can be found in the Portal under Settings, Site Administration, 
  API Keys.  Note: a Read Only key will _only_ be able to place GET calls.
  If you want to make changes (PUT, POST, or DELETE calls) you must get a
  Full Access key.

Installation:
- Copy call-servers.rb and wlslib.rb to the same directory in your path. 
wlslib.rb will also be found if you copy it to any directory in your
ruby library search path, which can be seen by running
echo 'puts $:' | irb


Sample invocations:

#==== Command line help
#See help text and parameters:
call-servers.rb -h


#Example of GET calls

#Retrieve basic server info for all servers in any group with
#"production" in the group name:
call-servers.rb -i aabbcc00 -g "production" -u '/' | less

#Same as above, but "pretty print" (multiline indented format) and include the "staging" groups too:
call-servers.rb -i aabbcc00 -g "production" -g "staging" -u '/' -p | less

#List server issues for _all_ active servers:
call-servers.rb -i aabbcc00 -s "" -u '/issues' -p | less


#Example of a PUT call

#Move all servers with "cloud1" in their server names into a new group. 
#You'll need the group ID first; this can be found by running
#"halo-get.rb -i aabbcc00 -u '/groups' -p | less" (halo-get.rb should be
#available from the same place where you found call-servers.rb).
echo '{ "server": { "group_id": "0123456789abcdef0123456789abcdef" } }' \
 | call-servers.rb -i aabbcc00 -s "cloud1" -u '/' -p | less


#Example of a POST call

#Create an account on all servers in groups with "web" in their group
#names or "http-" in the server names.
echo '{ "account": { "username": "bob", "password": { "length": 10, "include_special": true, "include_numbers": true, "include_uppercase": false } } }' \
 | call-servers.rb -i aabbcc00 -g 'web' -s 'http-' -m POST -u '/accounts'
#As this action happens asynchronously, the response blocks will have
#the URLs that will provide the status for each server.  Requesting this
#status will give you the new password when created.

#As above, but get bob's account block from a file.  Here's user-bob.json :

{
 "account": {
  "username": "bob",
  "comment": "User Bob",
  "groups": "users",
  "ssh_authorized_keys": [
   { "key": "ssh-dsa AAAAe06448012e21a713e06448012e21a713e06448012e21a713e06448012e21a713=== bob" }
  ],
  "password": {
   "length": 10,
   "include_special": true,
   "include_numbers": true,
   "include_uppercase": false
  }
 }
}

call-servers.rb -i aabbcc00 -g 'web' -s 'http-' -m POST -u '/accounts' <user-bob.json



#Example of a DELETE call

#Remove account "bob" from all servers in any groups whose tags match "live":
call-servers.rb -i aabbcc00 -t 'live' -m DELETE -u '/accounts/bob'



#Suggestions for actions to take on each server
#If the PUT or POST needs a body, a sample body is on the following line.
#Any part of the URL in curly braces is a value you need to replace.

What you want				Command line params
Basic server info			-u '/'
Move server to group			-m PUT -u '/'
	{ "server": { "group_id": "{target_group_id}" } }
Remove server from a server group	-m PUT -u '/'
	{ "server": { "group_id": "{unassigned_group_id}" } }
List server issues			-u '/issues'
List server local accounts		-u '/accounts'
Find accounts by name			-u '/accounts?search[username]={username}'
Find accounts by UID			-u '/accounts?search[uid]={uid}'
Server account details			-u '/accounts/{username}'
Create server account			-m POST -u '/accounts'
	{ "account": { "username": "bob", "comment": "User Bob", "groups": "users", "password": { "length": 10, "include_special": true, "include_numbers": true, "include_uppercase": false } } }
Reset password for server account	-m PUT -u '/accounts/{username}/password'
	{ "password": { "length": 10, "include_special": true, "include_numbers": true, "include_uppercase": false } }
Disable server account			-m PUT -u '/accounts/{username}'
	{ "account": { "active": false } }
Enable server account			-m PUT -u '/accounts/{username}'
	{ "account": { "active": true } }
Update/replace ssh keys			-m PUT -u '/accounts/{username}'
	{ "account": { "ssh_authorized_keys": [ { "key": "ssh-dsa AAAAe06448012e21a713e06448012e21a713e06448012e21a713e06448012e21a713=== bob" } ] } }
Remove ssh keys				-m PUT -u '/accounts/{username}'
	{ "account": { "ssh_authorized_keys": [ ] } }
Remove server account			-m DELETE -u '/accounts/{username}'
Launch configuration scan of server	-m POST -u '/scans'
	{ "scan": { "module": "sca" } }
Launch vulnerability scan of server	-m POST -u '/scans'
	{ "scan": { "module": "svm" } }
Launch server access scan of server	-m POST -u '/scans'
	{ "scan": { "module": "sam" } }
Launch file integrity scan of server	-m POST -u '/scans'
	{ "scan": { "module": "fim" } }

	For more details on these and other API calls available, see the
"CloudPassage API Developer Guide", which is at
https://support.cloudpassage.com/entries/23105662-CloudPassage-API-Developer-Guide
as of the time of this writing.




#Advanced uses:

#	If you manage more than one Halo Portal organization, you can
#place the same API request to all of them by specifying "-i {key}"
#multiple times (with corresponding lines for all keys in
#/etc/halo-api-keys .
call-servers.rb -i aabbcc00 -i 7890abcd -g 'web' -u '/' | less