Package: connector_def_runner
Connector Definition RunnerThis package provides the framework for connectors to be created with only schemas.  It can make HTTP
calls based on what is defined in the schema.Asset Schema StructureThe asset schema defines the authentication that is used for the connector.We currently support the following authentication methods:API Key (in the header, query parameters, or cookie)OAuth2Client CredentialPassword GrantHTTP BasicHTTP Bearer TokenEach authentication type has an asset file name and inputs that it requires. There is also ameta.securitykey in the asset schema that contains the configuration for the authentication.
The asset file name must match thenamefield, unless it's a custom asset (See the examples below).Examples:http_basicschema:asset/1name:http_basictitle:HTTP Basic Authenticationdescription:'Authenticatesusingusernameandpassword.'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.username:title:Usernamedescription:Usernametype:stringpassword:title:Passworddescription:Passwordtype:stringformat:passwordverify_ssl:title:Verify SSL Certificatesdescription:Verify SSL certificatetype:booleanhttp_proxy:title:HTTP(s) Proxydescription:A proxy to route requests through.type:stringrequired:-url-username-passwordmeta:security:type:httpscheme:basichttp_bearerschema:asset/1name:http_bearertitle:HTTP Bearer Authenticationdescription:'AuthenticatesusingbearertokensuchasaJWT,etc.'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.token:# NEVER CHANGE THIStitle:Token# name this properlydescription:The API key, token, etc.# name this properlytype:stringformat:passwordverify_ssl:title:Verify SSL Certificatesdescription:Verify SSL certificatetype:booleanhttp_proxy:title:HTTP(s) Proxydescription:A proxy to route requests through.type:stringrequired:-url-username-passwordmeta:security:type:httpscheme:bearerapikeyschema:asset/1name:apikeytitle:API Key Authenticationdescription:'AuthenticatesusinganAPIKey'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.x-apikey:# example, replace with correct key name for product.title:API Keydescription:API keytype:stringformat:passwordverify_ssl:title:Verify SSL Certificatesdescription:Verify SSL certificatetype:booleanhttp_proxy:title:HTTP(s) Proxydescription:A proxy to route requests through.type:stringrequired:-url-x-apikey# example, replace with correct key name for product.meta:security:type:apiKeyname:x-apikey# example, replace with correct key name for product.in:header, cookie or query# please select the one applicable to the API and remove the others.Thesecurityfield insidemetacould be an object or an array of objects.Examples:If you need to make a request with the header fieldx-apikeyand add its value from the inputs, you can use the following schema.
In this case thex-apikeyinput field is mandatory.inputs:type:objectproperties:x-apikey:# example, replace with correct key name for product.title:API Keytype:stringformat:passwordmeta:security:name:x-apikeyin:headerYou can also define a template using mustache syntax with the input values. For example, if you want
to add to your header the fieldAuthorization: ApiToken my_token, you can use the following schema
and usemy_tokenas an input value.inputs:type:objectproperties:token:# example, replace with correct key name for product.title:Tokentype:stringformat:passwordmeta:security:name:Authorizationin:headerformat:ApiToken {{token}}oauth2_client_credentialsThe optional fieldmeta.security.token_endpointon this example can be used to set a token endpoint which will be
concatenated to theurlinput to create the token url.  If you provide atoken_endpoint, thetoken_urlinput
should not be required.schema:asset/1name:oauth2_client_credentialstitle:Oauth 2.0 Client Credentialsdescription:'Authenticatesusingoauth2.0clientcredentials'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.token_url:title:Token URLtype:stringdefault:https://www.example.com/oauth/token# remove if this is static. Graph API requires tenant ID and would need the user input.client_id:title:Client IDdescription:The client IDtype:stringclient_secret:title:Client Secretdescription:The client secret.type:stringformat:passwordscope:title:Scopedescription:Permission scopes for this action.type:arrayitems:type:stringdefault:[]# Add array of scopes we think are needed for the action.verify_ssl:title:Verify SSL Certificatesdescription:Verify SSL certificatetype:booleanhttp_proxy:title:HTTP(s) Proxydescription:A proxy to route requests through.type:stringrequired:-url-client_id-client_secret-token_urlmeta:security:token_endpoint:"api/oauth2/token"type:oauth2flow:client_credentialsoauth2_passwordThe optional fieldmeta.security.token_endpointon this example can be used to set a token endpoint which will be
concatenated to theurlinput to create the token url.  If you provide atoken_endpoint, thetoken_urlinput
should not be required.schema:asset/1name:oauth2_passwordtitle:Oauth 2.0 Password Grantdescription:'Authenticatesusingoauth2.0clientcredentials'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.token_url:title:Token URLtype:stringdefault:https://www.example.com/oauth/token# remove if this is static. Graph API requires tenant ID and would need the user input.oauth2_username:title:OAuth2 Usernamedescription:The username for authenticationtype:stringoauth2_password:title:OAuth2 Passworddescription:The password for authenticationtype:stringformat:passwordclient_id:title:Client IDdescription:The client IDtype:stringclient_secret:title:Client Secretdescription:The client secret.type:stringformat:passwordscope:title:Scopedescription:Permission scopes for this action.type:arrayitems:type:stringdefault:[]# Add array of scopes we think are needed for the action.verify_ssl:title:Verify SSL Certificatesdescription:Verify SSL certificatetype:booleanhttp_proxy:title:HTTP(s) Proxydescription:A proxy to route requests through.type:stringrequired:-url-oauth2_username-oauth2_password-token_urlmeta:security:token_endpoint:"api/oauth2/token"type:oauth2flow:passwordAction Schema StructureThe action schema will include the following fields:schema: The schema type, this differentiates the assets from actions.title: The action titlename: The action internal namedescription: The action descriptioninputs: object of input fieldsoutput: object with the output fieldsmeta:endpoint: The HTTP endpointmethod: The HTTP methodExample schema:schema:action/1title:Delete Indicatorname:delete_indicatordescription:Deletes an indicatorinputs:type:objectproperties:json_body:title:JSON Bodytype:objectproperties:id:title:IDtype:stringrequired:-idadditionalProperties:falserequired:-json_bodyadditionalProperties:falaseoutput:type:objectproperties:status_code:title:Status Codetype:numbermeta:endpoint:iocs/entities/indicators/v1method:DELETEInputsTheinputsfield must be an object type with the following properties:headers: Headers to send with the request.parameters: Parameters to send in the query string for the request.data_body: Raw data send in the body of the request.json_body: JSON data to send in the body of the request.files: Object or array of objects with thecontentDisposition: attachmentproperty.path_parameters: Parameters to be replaced in the URL.Path ParametersYou can use mustaches to build the URL path based in thepath_parametersvalues. For example, if you have the following URL:https://api.crowdstrikefalcon/{{session_id}}/download/{{filename}}and the followingpath_parametersinputs field:inputs:type:objectproperties:path_parameters:title:Path Parameterstype:objectproperties:session_id:title:Session IDtype:stringfilename:title:File Nametype:stringrequired:-session_id-filenameThen the endpoint will be formatted using the input data in thepath_parametersobject.Filesfilesinputs could also include binary inputs and additional properties for the file. For example:inputs:type:objectproperties:attachments:title:Attachmentstype:arrayitems:contentDisposition:attachmenttype:objectadditionalProperties:falseproperties:file:type:stringformat:binaryfile_name:type:stringexamples:[]required:-attachmentsadditionalProperties:trueYou can also add additional properties into the attachment properties. For example, if you need to replicate the following
code:importrequestsheaders={'accept':'application/json'}files=[('file',open('decode.py;type=text/x-python-script','rb')),('permission_type',(None,'public')),('platform',(None,'linux'))]response=requests.post('https://api.crowdstrike.com/real-time-response/entities/scripts/v1',headers=headers,files=files)You can use the following input:inputs:type:objectproperties:attachments:title:Attachmentstype:arrayitems:contentDisposition:attachmenttype:objectadditionalProperties:falseproperties:file:type:stringformat:binaryfile_name:type:stringpermission_type:type:stringplatform:type:stringrequired:-attachmentsadditionalProperties:trueOutputsTheoutputfield works similar toinputs, with the difference that it could be an array instead of an object.It will contain the following properties:status_code: The status code of the response.response_headers: The headers of the response.reason: A text corresponding to the status code. For example, OK for 200, Not Found for 404.json_body: A JSON object of the responseresponse_text: If the response doesn't contain a JSON body and there is nofileproperty defined in the manifest, the response body will be returned in text format.file: Object or array of objects with thecontentDisposition: attachmentproperty.In order to get files as output, you must manually add a file property to the output section. See the following example:output:type:objectproperties:attachments:title:Attachmentstype:arrayitems:contentDisposition:attachmenttype:objectadditionalProperties:falseproperties:file:type:stringformat:binaryfilename:type:stringadditionalProperties:trueCustom ActionIn order to add custom actions, you must create a.pyfile and its file name must match with the corresponding manifest.
The source code must have aRunnerOverrideclass with the following interface:classRunnerOverride:def__init__(self,asset=asset,asset_schema=asset_schema,http_proxy=http_proxy):passdefrun(self,inputs=inputs,action_schema=action_schema):passFor example, suppose you want to create an action that makes an add operation using LDAP protocol.
You can create the following schema inconnector/config/actions/add.yaml:schema:action/1title:Addname:adddescription:>-The Add operation allows a client to request the addition of an entry into theLDAP directory.inputs:type:objectproperties:dn:title:Dnexamples:-CN=Charles,OU=friends,DC=testdomain,DC=localtype:stringobject_class:title:Object Classexamples:--persontype:arrayitems:type:stringattributes:title:Attributesexamples:-name:Charles Darwintype:objectproperties:name:title:Nameexamples:-Charles Darwintype:stringrequired:[]additionalProperties:truerequired:-dn-object_classadditionalProperties:trueoutput:type:objectproperties:result:title:Resulttype:numberdescription:title:Descriptiontype:stringdn:title:Dntype:stringmessage:title:Messagetype:stringreferrals:title:Referralstype:objectproperties:{}required:[]additionalProperties:truetype:title:Typetype:stringrequired:[]additionalProperties:truemeta:{}And then create the fileconnector/src/add.pywith the source code:importjsonimportosfromldap3importServer,ConnectionclassRunnerOverride(LdapActionBasic):def__init__(self,asset=asset,asset_schema=asset_schema,http_proxy=None):self.server=Server(asset["ip"],use_ssl=asset.get("verify_ssl",True),connect_timeout=asset.get("connect_timeout",10))self.conn=Connection(self.server,asset["username"],asset["password"],auto_bind=True)defrun(self,inputs=inputs,action_schema=None):self.conn.add(inputs)returnself.conn.resultCustom AuthenticationIn order to add custom authentication, you must create arunner_override.pyfile.
The file must have aRunnerOverrideclass with the following interface:classRunnerOverride:def__init__(self,asset=asset,asset_schema=asset_schema,http_proxy=http_proxy):passdefrun(self,inputs=inputs,action_schema=action_schema):passWhen this file is present, all actions will use it.Custom headersYou can build your own header field templates using mustache syntax. For example
if you need to define a custom header field like:auth: my_username:my_passwordfor all your actions, you can define the following asset schema:schema:asset/1title:HTTP Custom Authenticationdescription:'Authenticatesusingusernameandpassword.'inputs:type:objectproperties:url:title:URLdescription:A URL to the target host.type:stringdefault:https://www.example.com# change if it has a default cloud URL or remove if always custom.username:title:Usernamedescription:Usernametype:stringpassword:title:Passworddescription:Passwordtype:stringformat:passwordrequired:-url-username-passwordmeta:headers:auth:{{username}}:{{password}}This way the username and password will be replaced in themeta.headers.authfield. You can also define the same way custom headers for action schemas.