Python library for FireMon APIs

Developed using Python 3.8.0 and requests 2.20.1

Table of Contents

• About The Project
• Setup
• Dependencies
• Policy Planner Usage
• Security Manager Usage
• Policy Optimizer Usage
• Orchestration API Usage
• Project Structure
• Flow of Execution
• License

About The Project

This library/project is created to jumpstart your Orchestration API, Policy planner API, Security Manager API, or Policy Optimizer API projects.

Setup

Setup - PyPi Install:

• To install the library, run the following command from the terminal.

pip install security-manager-apis

Setup - PyPi Upgrade:

To upgrade the library, run the following command from the terminal.

pip install --upgrade security-manager-apis

pip 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 the setup.py file. Once done you can use the library wherever you want.

Dependencies

Pre-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 python3

Upgrade pip on Windows:

python -m pip install --upgrade pip

Policy Planner Usage

Initializing a Policy Planner Class

from security_manager_apis import policy_planner

policyplan = 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 to False.
• suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set to True.

Create a Policy Planner Ticket

policyplan.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 Ticket

policyplan.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 Tickets

policyplan.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 Ticket

policyplan.pull_pp_ticket(ticket_id: str)

• ticket_id: ID of ticket to be retrieved.

Retrieving Policy Planner Ticket Event History

policyplan.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 return

Retrieving Policy Planner Ticket Attachments

policyplan.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 return

Download Policy Planner Ticket Attachments

policyplan.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 fetch

Coding 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 Ticket

policyplan.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 Ticket

policyplan.unassign_pp_ticket(ticket_id: str)

• ticket_id: ID of ticket to remove assignee from.

Adding a Requirement to a Policy Planner Ticket

policyplan.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 Ticket

policyplan.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 Task

policyplan.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, rejected

Running PCA for a Policy Planner Ticket

policyplan.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_SEARCH
• enable_risk_sa: true or false

Adding Attachment to a Policy Planner Ticket

policyplan.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"
with open(file_name) as f:
    policyplan.add_attachment('38', file_name, f, 'test upload')

Uploading Requirements via CSV to Policy Planner Ticket

policyplan.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 to append, pass replace to replace all requirements on the ticket with the new CSV requirements

Uploading Requirements via CSV Code Example:

file_name = "test_req.csv"
with open(file_name) as f:
    policyplan.csv_req_upload('1', file_name, f)

Retrieving Requirements from a Policy Planner Ticket

policyplan.get_reqs(ticket_id: str)

• ticket_id: ID of ticket to retrieve requirements from.

Retrieving Changes from a Policy Planner Ticket

policyplan.get_changes(ticket_id: str)

• ticket_id: ID of ticket to retrieve requirements from.

Updating Change on a Policy Planner Ticket

policyplan.update_change(ticket_id: str, req_id: str, change_id: str, change_json: dict)

• ticket_id: ID of ticket
• req_id: ID of requirement change is tied to
• change_id: ID of change to update
• change_json: JSON of change update

Deleting Requirements from a Policy Planner Ticket

policyplan.del_all_reqs(ticket_id: str)

• ticket_id: ID of ticket to delete requirements from.

Approving Requirement in a Policy Planner Ticket

policyplan.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 Ticket

policyplan.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 Comments

policyplan.get_comments(ticket_id: str)

• ticket_id: ID of ticket to retrieve comments from.

Delete Comment from Policy Planner Ticket

policyplan.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 Session

policyplan.logout()

Security Manager Usage

Initializing a Security Manager Class

from security_manager_apis import security_manager

securitymanager = 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 to False.
• domain_id: The Domain ID for the targeted workflow.
• suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set to True.

Get List of Devices in Security Manager

securitymanager.get_devices()

Manual Device Retrieval

securitymanager.manual_device_retrieval(device_id: str)

• device_id: ID of device to retrieve.

Create Device Group

securitymanager.create_device_group(device_group_name: str)

• device_group_name: Name of device group to create.

Get Device Group by Name

securitymanager.get_device_group_by_name(device_group_name: str)

• device_group_name: Name of device group to create.

Add Device to Device Group

securitymanager.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 Route

securitymanager.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 File

securitymanager.bulk_add_supp_route(f)

• f: File stream.

Supplemental Route Text File Example

deviceId,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,true

Note: The first line of this file will not be processed, it serves as an informational header.

Supplemental Route Bulk Upload Code Example

with open('supp_route.txt') as f:
    securitymanager.bulk_add_supp_route(f)
f.close()

Security Manager SIQL Query

securitymanager.siql_query(query_type: str, query: str, page_size: int)

• query_type: What type of object to query. Options: secrule, policy, serviceobj, networkobj, device
• query: SIQL query to run.
• page_size: Number of results to return

Search for Device Zones

securitymanager.zone_search(device_id: str, page_size: int)

• device_id: Device ID
• page_size: Number of results to return

Retrieve Firewall Object

securitymanager.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, USER
• device_id: Device ID
• match_id: Match ID of targeted object

Retrieve Device Object

securitymanager.get_device_obj(device_id: str)

• device_id: Device ID

Retrieve Rule Documentation

securitymanager.get_rule_doc(device_id: str, rule_id: str)

• device_id: Device ID
• rule_id: Rule ID

Update Rule Documentation

securitymanager.update_rule_doc(device_id: str, rule_doc: dict)

• device_id: Device ID
• rule_doc: Rule documentation JSON

Rule 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 Session

securitymanager.logout()

Policy Optimizer Usage

Initializing a Policy Optimizer Class

from security_manager_apis import policy_optimizer

policyoptimizer = 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 to False.
• 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 to True.

Create a Policy Optimizer Ticket

policyoptimizer.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 JSON

policyoptimizer.get_po_ticket(ticket_id: str)

• ticket_id: ID of ticket to be retrieved.

Assign Policy Optimizer Ticket to User

policyoptimizer.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 Ticket

policyoptimizer.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:

• ruleActions Options:
  • MODIFYRULE, which prompts a value for modifyRuleOptions:
    • removeObjects, which prompts a value for removeOther
    • moveToRulePosition, which prompts a value for moveToPosition
    • modifyRuleOptions, which prompts a value for other
  • DISABLERULE, which prompts a value for disableRuleOptions:
    • couldNotFindOwner
    • accessNoLongerNeeded
    • other
  • REMOVERULE, which prompts a value for removeRuleOptions:
    • accessNoLongerNeeded
    • accessIsTooRisky
    • other

Cancel a Policy Optimizer Ticket

policyoptimizer.cancel_po_ticket(ticket_id: str)

• ticket_id: ID of ticket to cancel.

Query Policy Optimizer Tickets

policyoptimizer.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 Session

policyoptimizer.logout()

Orchestration API Usage

Initializing an Orchestration API Class

from security_manager_apis import orchestration_apis

orchestration = 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 to False.
• domain_id: The Domain ID for the targeted workflow.
• suppress_ssl_warning: Set to False by default. Will supress any SSL warnings when set to True.

Running Rule Recommendation

orchestration.rulerec_api(params: dict, req_json: dict)

• params: Parameters to use for recommendation.
• req_json: JSON of requirements to provide recommendation for.

Parameters Example

parameters = {'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 Assessment

orchestration.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 Structure

• application.properties - All the required URLS are placed here.
• get_properties_data.py - Read the properties file data and returns a parser
• policy_planner.py - Class to use Policy Planner APIs
• security_manager.py - Class to use Security Manager APIs
• policy_optimizer.py - Class to use Policy Optimizer APIs
• orchestration_apis.py - Class to use Crchestration APIs

Flow of Execution

As soon as you execute the command to run this library, Authentication class will be called which will internally call get_auth_token() of authentication_api.py from authenticate_user module 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.

License

MIT.