Package: security-manager-apis
Python library for FireMon APIsDeveloped using Python 3.8.0 and requests 2.20.1Table of ContentsAbout The ProjectSetupDependenciesPolicy Planner UsageSecurity Manager UsagePolicy Optimizer UsageOrchestration API UsageProject StructureFlow of ExecutionLicenseAbout The ProjectThis library/project is created to jumpstart your Orchestration API, Policy planner API, Security Manager API, or Policy Optimizer API projects.SetupSetup - PyPi Install:Toinstallthe library, run the following command from the terminal.pip install security-manager-apisSetup - PyPi Upgrade:Toupgradethe library, run the following command from the terminal.pip install --upgrade security-manager-apispip install -e .If you don't plan to make any modifications to the project but still want to use it across
your different projects, then do a local install.pip install .This will install all the dependencies listed in thesetup.pyfile. Once done
you can use the library wherever you want.DependenciesPre-requisite- Python 3.6 or greater version should be installed on your machine.Upgrade pip on Mac:NOTE: This is important because, apparently, some Mac apps rely on Python 2 version, so if you attempt to upgrade the Python 2.x to Python 3.x on Mac OS, you will eventually break some apps, perhaps critical apps.
With that in mind, you should not attempt to upgrade the current preinstalled Python release on the Mac; instead, you will just have the co-installation of Python 3 for full compatibility.brew install python3Upgrade pip on Windows:python -m pip install --upgrade pipPolicy Planner UsageInitializing a Policy Planner Classfromsecurity_manager_apisimportpolicy_plannerpolicyplan=policy_planner.PolicyPlannerApis(host:str,username:str,password:str,verify_ssl:bool,domain_id:str,workflow_name:str,suppress_ssl_warning:bool)host: Pointing to your FireMon server.username: The username that would be used to create the API connection to FireMon.password: The API password for the given user.domain_id: The Domain ID for the targeted workflow.workflow_name: The name of the targeted workflow.verify_ssl: Enabled by default. If you are running demo/test environment, good chance you'll need to set this one toFalse.suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set toTrue.Create a Policy Planner Ticketpolicyplan.create_pp_ticket(request_body:dict)request_body: JSON of ticket to be created.Request JSON Example:{"variables":{"summary":"string","businessNeed":"string","priority":"string","dueDate":"YYYY-MM-DD HH:MM:SS","applicationName":"string","customer":"string","externalTicketId":"string","notes":"string","requesterName":"string","requesterEmail":"string","applicationOwner":"string","carbonCopy":["string","string"]},"policyPlanRequirements":[{"sources":["string","string"],"destinations":["string","string"],"action":"string","services":["string","string"],"requirementType":"string","childKey":"string","variables":{}}]}Update a Policy Planner Ticketpolicyplan.update_pp_ticket(ticket_id:str,request_body:dict)ticket_id: ID of ticket to be updated.request_body: JSON of updates to apply to the ticket.Request JSON Example:{"variables":{"summary":"string"}}Querying for Policy Planner Ticketspolicyplan.siql_query_pp_ticket(siql_query:str,page_size:int)siql_query: SIQL Query to use in search.page_size: Number of results to return.Retrieving a Policy Planner Ticketpolicyplan.pull_pp_ticket(ticket_id:str)ticket_id: ID of ticket to be retrieved.Retrieving Policy Planner Ticket Event Historypolicyplan.pull_pp_ticket_events(ticket_id:str,page_size:int)ticket_id: ID of ticket to retrieve event history from.page_size: Number of events to returnRetrieving Policy Planner Ticket Attachmentspolicyplan.pull_pp_ticket_attachements(ticket_id:str,page_size=100)ticket_id: ID of ticket to retrieve event history from.page_size: Number of events to returnDownload Policy Planner Ticket Attachmentspolicyplan.download_pp_ticket_attachment(self,ticket_id:str,attachment_id:str)ticket_id: ID of ticket to retrieve event history from.attachment_id: ID of attachment to fetchCoding Example:attachment_resp=pp.download_pp_ticket_attachment(ticket_id,attachment_id)file_name=attachment_resp.headers['filename']open(file_name,'wb').write(attachment_resp.content)Assigning a Policy Planner Ticketpolicyplan.assign_pp_ticket(ticket_id:str,user_id:str)ticket_id: ID of ticket to assign user to.user_id: ID of user to be assigned.Unassigning a Policy Planner Ticketpolicyplan.unassign_pp_ticket(ticket_id:str)ticket_id: ID of ticket to remove assignee from.Adding a Requirement to a Policy Planner Ticketpolicyplan.add_req_pp_ticket(ticket_id:str,req_json:dict)ticket_id: ID of ticket to add requirement to.req_json: JSON of requirement to be added.Requirement JSON Example:{"requirements":[{"requirementType":"RULE","childKey":"add_access","variables":{"expiration":"2022-01-01T00:00:00+0000"},"destinations":["10.1.1.1/24"],"services":["tcp/22"],"sources":["10.0.0.0/24"],"action":"ACCEPT"}]}Replacing Requirements on a Policy Planner Ticketpolicyplan.replace_req_pp_ticket(self,ticket_id:str,req_json:dict)ticket_id: ID of ticket to add requirements to.req_json: JSON of requirements to be added.Completing a Policy Planner Ticket Taskpolicyplan.complete_task_pp_ticket(ticket_id:str,button_action:str)ticket_id: ID of ticket to add requirement to.button_action: Button value, options are: submit, complete, autoDesign, verify, approved, rejectedRunning PCA for a Policy Planner Ticketpolicyplan.run_pca(ticket_id:str,control_types:str,enable_risk_sa:str)ticket_id: ID of ticket to run PCA on.control_types: Control types as string array. Options: ALLOWED_SERVICES, CHANGE_WINDOW_VIOLATION, DEVICE_ACCESS_ANALYSIS, DEVICE_PROPERTY, DEVICE_STATUS, NETWORK_ACCESS_ANALYSIS, REGEX, REGEX_MULITPATTERN, RULE_SEARCH, RULE_USAGE, SERVICE_RISK_ANALYSIS, ZONE_MATRIX, ZONE_BASED_RULE_SEARCHenable_risk_sa: true or falseAdding Attachment to a Policy Planner Ticketpolicyplan.add_attachment(ticket_id:str,file_name:str,f,description:str):ticket_id: ID of ticket to add attachment to.filename: File name of attachment.f: file stream.description: Description of file.Adding Attachment Code Example:file_name="test_file.txt"withopen(file_name)asf:policyplan.add_attachment('38',file_name,f,'test upload')Uploading Requirements via CSV to Policy Planner Ticketpolicyplan.csv_req_upload(ticket_id:str,file_name:str,f,behavior="append"):ticket_id: ID of ticket to add attachment to.filename: File name of attachment.f: file stream.behavior: Defaulted toappend, passreplaceto replace all requirements on the ticket with the new CSV requirementsUploading Requirements via CSV Code Example:file_name="test_req.csv"withopen(file_name)asf:policyplan.csv_req_upload('1',file_name,f)Retrieving Requirements from a Policy Planner Ticketpolicyplan.get_reqs(ticket_id:str)ticket_id: ID of ticket to retrieve requirements from.Retrieving Changes from a Policy Planner Ticketpolicyplan.get_changes(ticket_id:str)ticket_id: ID of ticket to retrieve requirements from.Updating Change on a Policy Planner Ticketpolicyplan.update_change(ticket_id:str,req_id:str,change_id:str,change_json:dict)ticket_id: ID of ticketreq_id: ID of requirement change is tied tochange_id: ID of change to updatechange_json: JSON of change updateDeleting Requirements from a Policy Planner Ticketpolicyplan.del_all_reqs(ticket_id:str)ticket_id: ID of ticket to delete requirements from.Approving Requirement in a Policy Planner Ticketpolicyplan.approve_req(ticket_id:str,req_id:str)ticket_id: ID of ticket that the requirement is tied to.req_id: ID of requiremnt to approve.Add Comment to Policy Planner Ticketpolicyplan.add_comment(ticket_id:str,comment:str)ticket_id: ID of ticket to add comment to.comment: Content of comment.Retrieve All Policy Planner Ticket Commentspolicyplan.get_comments(ticket_id:str)ticket_id: ID of ticket to retrieve comments from.Delete Comment from Policy Planner Ticketpolicyplan.del_comment(ticket_id:str,comment_id:str)ticket_id: ID of ticket to delete comment from.comment_id: ID of comment to delete.Ending a Policy Planner Sessionpolicyplan.logout()Security Manager UsageInitializing a Security Manager Classfromsecurity_manager_apisimportsecurity_managersecuritymanager=security_manager.SecurityManagerApis(host:str,username:str,password:str,verify_ssl:bool,domain_id:str,suppress_ssl_warning:bool)host: Pointing to your FireMon server.username: The username that would be used to create the API connection to FireMon.password: The API password for the given user.verify_ssl: Enabled by default. If you are running demo/test environment, good chance you'll need to set this one toFalse.domain_id: The Domain ID for the targeted workflow.suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set toTrue.Get List of Devices in Security Managersecuritymanager.get_devices()Manual Device Retrievalsecuritymanager.manual_device_retrieval(device_id:str)device_id: ID of device to retrieve.Create Device Groupsecuritymanager.create_device_group(device_group_name:str)device_group_name: Name of device group to create.Get Device Group by Namesecuritymanager.get_device_group_by_name(device_group_name:str)device_group_name: Name of device group to create.Add Device to Device Groupsecuritymanager.add_to_device_group(device_group_id:str,device_id:str)device_group_id: ID of device group to add device to.device_id: ID of device to add to device group.Adding a Supplemental Routesecuritymanager.add_supp_route(device_id:str,supplemental_route:dict)device_id: ID of device to retrieve.supplemental_route: JSON of supplemental route.Supplemental Route JSON Example{"destination":"10.0.0.25","deviceId":"2","drop":false,"gateway":"10.0.0.26","interfaceName":"port1","metric":3}Bulk Adding Supplemental Route via Text Filesecuritymanager.bulk_add_supp_route(f)f: File stream.Supplemental Route Text File ExampledeviceId,interfaceName,destination,gateway,virtualRouter,nextVirtualRouter,metric,drop
2,port1,10.0.0.25,10.0.0.26,,,4,true
2,,10.0.0.25,10.0.0.26,Default,Default,4,trueNote: The first line of this file will not be processed, it serves as an informational header.Supplemental Route Bulk Upload Code Examplewithopen('supp_route.txt')asf:securitymanager.bulk_add_supp_route(f)f.close()Security Manager SIQL Querysecuritymanager.siql_query(query_type:str,query:str,page_size:int)query_type: What type of object to query. Options: secrule, policy, serviceobj, networkobj, devicequery: SIQL query to run.page_size: Number of results to returnSearch for Device Zonessecuritymanager.zone_search(device_id:str,page_size:int)device_id: Device IDpage_size: Number of results to returnRetrieve Firewall Objectsecuritymanager.get_fw_obj(obj_type:str,device_id:str,match_id:str)obj_type: Type of firewall object. Options: NETWORK, SERVICE, ZONE, APP, PROFILE, SCHEDULE, URL_MATCHER, USERdevice_id: Device IDmatch_id: Match ID of targeted objectRetrieve Device Objectsecuritymanager.get_device_obj(device_id:str)device_id: Device IDRetrieve Rule Documentationsecuritymanager.get_rule_doc(device_id:str,rule_id:str)device_id: Device IDrule_id: Rule IDUpdate Rule Documentationsecuritymanager.update_rule_doc(device_id:str,rule_doc:dict)device_id: Device IDrule_doc: Rule documentation JSONRule Doc JSON Example:{"ruleId":"16959bc0-b9f7-436b-9851-aac6f3d98963","deviceId":3,"props":[{"ruleId":"16959bc0-b9f7-436b-9851-aac6f3d98963","ruleCustomPropertyDefinition":{"id":1,"customPropertyDefinition":{"id":1,"name":"Business Justification","key":"business_justification","type":"STRING_ARRAY","filterable":true,"inheritFromMgmtStation":false},"name":"Business Justification","key":"business_justification","type":"STRING_ARRAY"},"customProperty":{"id":1,"name":"Business Justification","key":"business_justification","type":"STRING_ARRAY","filterable":true,"inheritFromMgmtStation":false},"stringarray":["test update"]}]}Ending a Security Manager Sessionsecuritymanager.logout()Policy Optimizer UsageInitializing a Policy Optimizer Classfromsecurity_manager_apisimportpolicy_optimizerpolicyoptimizer=policy_optimizer.PolicyOptimizerApis(host:str,username:str,password:str,verify_ssl:bool,domain_id:str,workflow_name:str,suppress_ssl_warning:bool)host: Pointing to your FireMon server.username: The username that would be used to create the API connection to FireMon.password: The API password for the given user.verify_ssl: Enabled by default. If you are running demo/test environment, good chance you'll need to set this one toFalse.domain_id: The Domain ID for the targeted workflow.workflow_name: The name of the targeted workflow.suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set toTrue.Create a Policy Optimizer Ticketpolicyoptimizer.create_pp_ticket(request_body:dict)request_body: JSON of ticket to be created.Request JSON Example:{"deviceId":1,"policyId":"62c7344a-31b9-40a6-8e7e-0c9cd6407fbe","ruleId":"16959bc0-b9f7-436b-9851-aac6f3d98963"}Retrieve Policy Optimizer Ticket JSONpolicyoptimizer.get_po_ticket(ticket_id:str)ticket_id: ID of ticket to be retrieved.Assign Policy Optimizer Ticket to Userpolicyoptimizer.assign_po_ticket(ticket_id:str,user_id:str)ticket_id: ID of ticket to assign user to.user_id: ID of User to be assigned.Complete a Policy Optimizer Ticketpolicyoptimizer.complete_po_ticket(ticket_id:str,decision:dict)ticket_id: ID of ticket to complete.decision: JSON of decision to Certify/Decertify rule.Certify JSON Example:{"variables":{"ruleDecision":"certify","certifyRemarks":"string","nextReviewDate":"2022-01-01T00:00:00-0500"}}Decertify JSON Example:{"variables":{"ruleDecision":"decertify","ruleActions":"string","modifyRuleOptions":"string","moveToPosition":"string","removeOther":"string","disableRuleOptions":"string","removeRuleOptions":"string","decertifyRuleReason":"string"}}Decertify JSON Structure:ruleActionsOptions:MODIFYRULE, which prompts a value formodifyRuleOptions:removeObjects, which prompts a value forremoveOthermoveToRulePosition, which prompts a value formoveToPositionmodifyRuleOptions, which prompts a value forotherDISABLERULE, which prompts a value fordisableRuleOptions:couldNotFindOwneraccessNoLongerNeededotherREMOVERULE, which prompts a value forremoveRuleOptions:accessNoLongerNeededaccessIsTooRiskyotherCancel a Policy Optimizer Ticketpolicyoptimizer.cancel_po_ticket(ticket_id:str)ticket_id: ID of ticket to cancel.Query Policy Optimizer Ticketspolicyoptimizer.siql_query_po_ticket(parameters:dict)parameters: Parameters of query.Params Example:params={'q':"review { workflow = 1 AND status ~ 'Review' }",'pageSize':20,'domainId':1,'sortdir':'asc'}Ending a Policy Optimizer Sessionpolicyoptimizer.logout()Orchestration API UsageInitializing an Orchestration API Classfromsecurity_manager_apisimportorchestration_apisorchestration=orchestration_apis.OrchestrationApis(host:str,username:str,password:str,verify_ssl:bool,domain_id:str,suppress_ssl_warning=False)host: Pointing to your FireMon server.username: The username that would be used to create the API connection to FireMon.password: The API password for the given user.verify_ssl: Enabled by default. If you are running demo/test environment, good chance you'll need to set this one toFalse.domain_id: The Domain ID for the targeted workflow.suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set toTrue.Running Rule Recommendationorchestration.rulerec_api(params:dict,req_json:dict)params: Parameters to use for recommendation.req_json: JSON of requirements to provide recommendation for.Parameters Exampleparameters={'deviceGroupId':1,'addressMatchingStrategy':'INTERSECTS','modifyBehavior':'MODIFY','strategy':None}Requirements Example{"requirements":[{"requirementType":"RULE","childKey":"add_access","variables":{"expiration":"2022-01-01T00:00:00+0000"},"destinations":["10.1.1.1/24"],"services":["tcp/22"],"sources":["10.0.0.0/24"],"action":"ACCEPT"}]}Running Pre-Change Assessmentorchestration.pca_api(device_id:str,req_json:dict)device_id: ID of device to use when running Pre-Change Assessment.req_json: JSON of requirements to provide recommendation for.Requirements Example{"requirements":[{"requirementType":"RULE","childKey":"add_access","variables":{"expiration":"2022-01-01T00:00:00+0000"},"destinations":["10.1.1.1/24"],"services":["tcp/22"],"sources":["10.0.0.0/24"],"action":"ACCEPT"}]}Project Structureapplication.properties- All the required URLS are placed here.get_properties_data.py- Read the properties file data and returns a parserpolicy_planner.py- Class to use Policy Planner APIssecurity_manager.py- Class to use Security Manager APIspolicy_optimizer.py- Class to use Policy Optimizer APIsorchestration_apis.py- Class to use Crchestration APIsFlow of ExecutionAs soon as you execute the command to run this library, Authentication class will be called which will internally call get_auth_token() ofauthentication_api.pyfromauthenticate_usermodule only once and
auth token will be set in the headers.
Then we pass headers to the HTTP requests so that user should get authenticated and can access the endpoints safely.LicenseMIT.