def add_object_tag(self, args):
"""Adds a security Tag to an object.
Required Arguments:
* `tag` - The name of the Tag.
* `object_id` - The ID of the object.
* `object_type` - The numeric type of the object.
Returns: Success message successful, error message on failure.
Valid and currently implemented `object_type` values are:
* `User` = 1
* `Asset` = 2
* `Task` = 3
* `Canvas Item` = 50
* `Deployment` = 70
* `Application Template` = 71
"""
# this is a admin function
if not api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_msg="Only Administrators can perform this function.")
# define the required parameters for this call
required_params = ["tag", "object_id", "object_type"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
tag.ObjectTags.Add(args["tag"], args["object_id"], args["object_type"])
catocommon.write_add_log(api._USER_ID, args["object_type"], args["object_id"], args["object_id"], "Tag [%s] added to object via API." % args["tag"])
return R(response="Tag successfully added to object.")
def create_task_from_json(self, args):
"""Create a new Task from a JSON Task backup document.
Required Arguments:
* `json` - A properly formatted JSON representation of a Task.
Returns: A [Task Object](restapi/api-response-objects.html#Task){:target="_blank"}.
"""
# define the required parameters for this call
required_params = ["json"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
t = task.Task()
t.FromJSON(args["json"], args.get("on_conflict"))
result, msg = t.DBSave()
if result:
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Task, t.ID, t.Name, "Task created.")
if args.get("output_format") == "json":
return R(response=t.AsJSON())
elif args.get("output_format") == "text":
return R(response=t.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=t.AsXML())
else:
return R(err_code=R.Codes.CreateError, err_detail=msg)
def create_tag(self, args):
"""Creates a new security Tag.
Required Arguments:
* `name` - The name of the new Tag. (AlphaNumeric ONLY. Cannot contain spaces, punctuation or special characters.)
Optional Arguments:
* `description` - Describe the Tag.
Returns: The new [Tag Object](restapi/api-response-objects.html#Tag){:target="_blank"} if successful, error message on failure.
"""
# this is a admin function, kick out
if not api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_msg="Only Administrators can perform this function.")
# define the required parameters for this call
required_params = ["name"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
obj = tag.Tag(args["name"], args.get("description"))
obj.DBCreateNew()
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Tag, obj.Name, obj.Name, "Tag created by API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def create_task(self, args):
"""Create a new Task.
Required Arguments:
* `name` - a name for the new Task.
Optional Arguments:
* `code` - a Task code.
* `desc` - a Task description.
Returns: A [Task Object](restapi/api-response-objects.html#Task){:target="_blank"}.
"""
# define the required parameters for this call
required_params = ["name"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
code = args["code"] if "code" in args else ""
desc = args["desc"] if "desc" in args else ""
t = task.Task().DBCreateNew(args["name"], code, desc)
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Task, t.ID, t.Name, "Task created.")
if args.get("output_format") == "json":
return R(response=t.AsJSON())
elif args.get("output_format") == "text":
return R(response=t.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=t.AsXML())
def _save(t):
result, err = t.DBSave()
if result:
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Task, t.ID, t.Name, "Created by import.")
items.append({"type": "task", "id": t.ID, "Name": t.Name, "Info": "Success"})
else:
if err:
items.append({"type": "task", "id": t.ID, "Name": t.Name, "Info": err})
else:
items.append({"type": "task", "id": t.ID, "Name": t.Name, "Info": "Unable to create Task. No error available."})
def create_credential(self, args):
"""Creates a new Shared Credential.
> Only a 'Developer' can create Credentials.
Required Arguments:
* `name` - The full name of the user.
* `username` - A login name for the user.
* `password` - Password for the user. If password is not provided, a random password will be generated.
Optional Arguments:
* `description` - Description of the Credential.
* `privileged` = Additional password required to put certain devices into 'privileged' mode.
* `domain` - A domain for the Credential.
Returns: A [Credential Object](restapi/api-response-objects.html#Credential){:target="_blank"}.
"""
# this is a admin function, kick out
if not api._DEVELOPER:
return R(err_code=R.Codes.Forbidden, err_msg="Only Developers or Administrators can perform this function.")
# define the required parameters for this call
required_params = ["name", "username", "password"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
# a little different than the others ... credential objects must be instantiated before calling DBCreateNew
obj = asset.Credential()
obj.FromArgs(args["name"], args.get("description"), args["username"], args["password"],
0, args.get("domain"), args.get("privileged"), None)
result = obj.DBCreateNew()
if not result:
return R(err_code=R.Codes.CreateError, err_detail="Unable to create Credential.")
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Credential, obj.ID, obj.Name, "Credential created by API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def create_account(self, args):
"""
Creates a Cloud Account.
Required Arguments:
* `name` - a name for the new Account.
* `provider` - one of the valid cloud providers.
* `login` - the login id (access key) for this Account.
* `password` - a password (secret key) for this Account.
* `default_cloud` - the name of a default Cloud for this Account.
Optional Arguments:
* `account_number` - an Account number.
Returns: The new [Cloud Account Object](restapi/api-response-objects.html#CloudAccount){:target="_blank"}.
"""
# this is a developer function
if not api._DEVELOPER:
return R(err_code=R.Codes.Forbidden, err_msg="Only Developers or Administrators can perform this function.")
required_params = ["name", "provider", "login", "password", "default_cloud"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
name = args.get("name")
provider = args.get("provider")
login = args.get("login")
pw = args.get("password")
default_cloud = args.get("default_cloud")
acct_number = args.get("account_number", "")
obj = cloud.CloudAccount.DBCreateNew(provider, name, login, pw, acct_number, default_cloud)
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.CloudAccount, obj.ID, obj.Name, "Account created via API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def create_cloud(self, args):
"""Creates a Cloud.
Required Arguments:
* `name` - a name for the new Cloud.
* `provider` - one of the valid cloud providers.
* `apiurl` - URL of the Cloud API endpoint.
* `apiprotocol` - Cloud API endpoint protocol.
Optional Arguments:
* `default_account` - the name of a default Account for this Cloud.
Returns: The new [Cloud Object](restapi/api-response-objects.html#Cloud){:target="_blank"}.
"""
# this is a developer function
if not api._DEVELOPER:
return R(err_code=R.Codes.Forbidden, err_msg="Only Developers or Administrators can perform this function.")
required_params = ["name", "provider", "apiurl", "apiprotocol"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
name = args.get("name")
provider = args.get("provider")
apiurl = args.get("apiurl")
apiprotocol = args.get("apiprotocol")
default_account = args.get("default_account")
obj = cloud.Cloud.DBCreateNew(name, provider, apiurl, apiprotocol, "", default_account)
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Cloud, obj.ID, obj.Name, "Cloud created via API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def add_cloud_keypair(self, args):
"""Adds a Key Pair to a Cloud.
Required Arguments:
* `cloud` - Name or ID of the Cloud to update.
* `name` - a name for the Key Pair.
* `private_key` - the private key.
Optional Arguments:
* `passphrase` - a passphrase for this Key Pair.
Returns: A list of [Cloud KeyPair Objects](restapi/api-response-objects.html#CloudKeyPair){:target="_blank"}.
"""
# this is a developer function
if not api._DEVELOPER:
return R(err_code=R.Codes.Forbidden, err_msg="Only Developers or Administrators can perform this function.")
required_params = ["cloud", "name", "private_key"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
obj = cloud.Cloud()
obj.FromName(args["cloud"])
obj.AddKeyPair(args.get("name"), args.get("private_key"), args.get("passphrase"))
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.CloudKeyPair, obj.ID, obj.Name, "KeyPair [%s] added to Cloud via API." % args.get("name"))
# so what do we return when we add a keypair? How about a list of all the keypairs.
if args.get("output_format") == "json":
return R(response=obj.KeyPairsAsJSON())
elif args.get("output_format") == "text":
return R(response=obj.KeyPairsAsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.KeyPairsAsXML())
def create_asset(self, args):
"""Creates an Asset.
Required Arguments:
* name - a name for the new Asset.
Optional Arguments:
* `status` - either 'Active' or 'Inactive'. ('Active' if omitted.)
* `db_name` - a Database name.
* `address` - the network address of the Asset.
* `port` - a service port for the Address.
* `conn_string` - some Assets make their connections via an explicit connection string.
* `user` - a User ID to associate with this Asset.
* `password` - a Password to associate with this Asset.
* `shared_credential` - the name of a Shared Credential to use.
**Regarding Credentials:**
Credentials are optional on an Asset, however if provided there are rules.
Explicit details can be associated with *only this Asset*, or a Shared Credential can be specified.
The minimum required to create a LOCAL set of credentials on this Asset are:
* `user` - a User ID for the Credential
* `password` - a Password for the Credential
To specify a Shared Credential, provide the `shared_credential` argument, which is the name of an existing Credential.
Returns: An [Asset Object](restapi/api-response-objects.html#Asset){:target="_blank"}.
"""
# this is a developer function
if not api._DEVELOPER:
return R(err_code=R.Codes.Forbidden, err_msg="Only Developers or Administrators can perform this function.")
required_params = ["name"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
# build a dictionary suitable for creating an asset
_a = {
"Name": args.get("name"),
"Status": args.get("status"),
"DBName": args.get("db_name"),
"Port": args.get("port"),
"Address": args.get("address"),
"ConnString": args.get("conn_string"),
"Credential": {
"SharedOrLocal": 0 if args.get("shared_credential") else 1,
"Username": args.get("user"),
"Password": args.get("password"),
"Name": args.get("shared_credential")
}
}
obj, err = asset.Asset.DBCreateNew(_a)
if err:
return R(err_code=R.Codes.CreateError, err_detail=err)
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.Asset, obj.ID, obj.Name, "Asset created via API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
def create_user(self, args):
"""Creates a new user account.
Only an 'Administrator' can create other users. If the credentials used for this API call
are not an Administrator, the call will not succeed.
Required Arguments:
* `user` - A login name for the user.
* `name` - The full name of the user.
* `role` - The users role. Valid values:
* Administrator
* Developer
* User
Optional Arguments:
* `password` - Password for the user. If password is not provided, a random password will be generated.
* `email` - Email address for the user. Required if 'password' is omitted.
* `authtype` - 'local' or 'ldap'. Default is 'local' if omitted.
* `forcechange` - Require user to change password. Default is 'true' if omitted. (Valid values: 'true' or 'false')
* `status` - Status of the new account. Default is 'enabled' if omitted. (Valid values: enabled, disabled, locked)
* `expires` - Expiration date for this account. Default is 'never expires'. Must be in mm/dd/yyyy format.
* `groups` - A list of groups the user belongs to. Group names cannot contain spaces. Comma delimited list.
* `get_token` - If true, will return an automatic login token. (Valid values: 1, yes, true)
Returns: A [User Object](restapi/api-response-objects.html#User){:target="_blank"}.
"""
# this is a admin function, kick out
if not api._ADMIN:
return R(err_code=R.Codes.Forbidden, err_msg="Only Administrators can perform this function.")
# define the required parameters for this call
required_params = ["user", "name", "role"]
has_required, resp = api.check_required_params(required_params, args)
if not has_required:
return resp
generate = True if not args.get("password") else False
if generate and not args.get("email"):
return R(err_code=R.Codes.Exception, err_detail="Email is required if password is omitted.")
status = args.get("status", 1) # default if omitted is 'enabled'
groups = args.get("groups").split(",") if args.get("groups") else None
# validate the expiration date is properly formatted, otherwise pass None
import dateutil.parser as parser
expiration_dt = None
try:
tmp = parser.parse(args.get("expires"))
expiration_dt = tmp.strftime("%m/%d/%Y")
except:
pass
obj = catouser.User.DBCreateNew(username=args["user"],
fullname=args["name"],
role=args["role"],
password=args.get("password"),
generatepw=generate,
authtype=args.get("authtype"),
forcechange=args.get("forcechange"),
email=args.get("email"),
status=status,
expires=expiration_dt,
groups=groups)
# do we get a login token?
if catocommon.is_true(args.get("get_token")):
obj.GetToken()
if obj:
catocommon.write_add_log(api._USER_ID, catocommon.CatoObjectTypes.User, obj.ID, obj.LoginID, "User created by API.")
if args.get("output_format") == "json":
return R(response=obj.AsJSON())
elif args.get("output_format") == "text":
return R(response=obj.AsText(args.get("output_delimiter"), args.get("header")))
else:
return R(response=obj.AsXML())
else:
return R(err_code=R.Codes.CreateError, err_detail="Unable to create User.")
def WriteObjectAddLog(oType, sObjectID, sObjectName, sLog=""):
catocommon.write_add_log(GetSessionUserID(), oType, sObjectID, sObjectName, sLog)
