Fortigate FortiManager Powershell Module

This Powershell Module is a wrapper for the API of Fortigate FortiManager
Explore the docs »

Report Bug · Request Feature

Table of Contents

1. About The Project
   • Built With
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. Use-Cases - Why was this module created?
5. Roadmap
6. Contributing
7. License
8. Contact
9. Acknowledgements

About The Project

This Powershell Module is a wrapper for the API of Fortnet FortiManager. Fortnet FortiManager is a solution for managing multiple instances of Fortigate firewalls.

The API is documented in the Fortinet Developer Network.

Built With

• PSModuleDevelopment
• psframework

Getting Started

To get a local copy up and running follow these simple steps.

Prerequisites

• Powershell 7.x (Core) (If possible get the latest version)
  Maybe it's working under 5.1, just did not test it
• A Fortinet FortiManager Manager and HTTPS enable with JSON API enable for the user
  • Go on WebGUI of your FortiManager, on System Settings
  • Go Administrators
  • Click on Create New
  • and create a new user and don't forget to enable JSON API Access to Read-Write

Installation

The releases are published in the Powershell Gallery, therefor it is quite simple:

Install-Module FortigateManager -Force

Usage

The module is a wrapper for the Fortinet FortiManager API. For getting started take a look at the integrated help of the included functions. As inspiration you can take a look at the use-cases which led to the development of this module.

Currently supported firewall object types (v2.0)

The following types of objects can handled (the list is not exhaustive):

functionPrefix	Get-FM*	New-FMObj*	Add-FM*	Update-FM*	Rename-FM*	Remove-FM*
Address	X	X	X	X	X	X
AddressGroup	X	X	X	X	X	X
FirewallPolicy	X	X	X	X	*	X
FirewallService	X	X	X	X	*
FirewallInterfaces	X	X	X	X	X	X
DeviceInfo	X
Task	X
Firewall Hitcounts	X
ADOM LockStatus	X

An * in Rename means there is no specific function for it, you may use the Update-FM* to do it manually.

Additional Meta Functions

• Connect-FM - Connects to an instance
• Disconnect-FM - Disconnects
• Get-FMAdomLockStatus - Check if the DOM is locked
• Lock-FMAdom - Lock the ADOM for changes
• Publish-FMAdomChange - Publish those changes (aka save)
• Unlock-FMAdom - Unlock to make it available for change to other users
• Get-FMFirewallHitCount - How many hits does which rule get?
• Move-FMFirewallPolicy - Move a policy before/after another one
• Convert-FMIpAddressToMaskLength - Converts a IP Subnet-Mask to a Mask Length
• Convert-FMSubnetMask - Converts a subnet mask between long and short-version
• Invoke-FMAPI - The magical black box which handles the API requests

Use-Cases or Why was the module developed?

Background

Our company uses the Fortinet Manager for administration of 8 production firewalls. The policies were separated into 8 policy packages and no policy package was the same. In a refactoring project we created a new firewall design based on

• categorizing the vlans into security levels
• creating hierarchical address groups based on the security levels and locations
• building new default policies based on those new objects

Part One

First task was to import 400 new address objects from Excel. The business requirements were simple:

• Login to the manager (Connect-FM)
• Query existing addresses (Get-FMAddress) and address groups (Get-FMADdressGroup)
• Create new objects for the API (New-FMObjAddressGroup and New-FMObjAddress) out of the excel file (Thanks to ImportExcel)
• Lock the ADOM for writing (Lock-FMAdom) - Breaking Change in v2.0.0 Provide the default RevisionNote as a parameter
• Add the new address objects to the ADOM (Add-FMAddress and Add-FMAddressGroup)
• Save the changes (Publish-FMAdomChange)
• Unlock the ADOM after work (UnlockFMAdom)

For testing purposes the antagonists of Add where needed (Remove-FMAddress, Remove-FMAddressGroup), and updating the objects would have been nice, too (you get it, Update-*).

Part Two

The new default address objects could be imported, the new default policy rules could be implemented... But where? We had 8 policy packages....

One solution would have been to add the policies to the Global Header config... But beside the firewalls within the project scope the Manager appliance was also in charge of the main location firewalls which would receive the new policies, too. That's not desirable.

New plan:

• Create a new policy package, add all firewall devices/vdoms to the new package
• Create the new global policy rules
• Foreach existing policy package
  • Read the existing rules (Get-FMFirewallPolicy)
  • Modify them (rename, add the previous "Installation Targets" as "Install On" attribute (scope member))
  • Add the modified rule to the new policy package (Add-FMFirewallPolicy)
• Apply the new Package to each VDOM
  • The global rules would target all devices
  • The prior copied rules would target specific VDOMs

Part three

As the module has the ability to read/create/add Firewall policy rules, why not import the new global rules directly from excel? No problem, just had to implement the functions around Firewall Services (Get/Add/Update-FMFirewallService). Voila, every necessary task can be automated.

Part four

I needed detailed log access which is handled by a Forti Analyzer instance in our company. As the API structure is the same as for the manager I added the Search-FMALog function to this module in release v3.0.0.

Example code

# Connect
$connection = Connect-FM -Credential $fortiCred -Url MyServer.MyCompany.com -verbose -Adom TEST

# Import some data from excel
$ipTable = Import-Excel -Path ".\ip-data.xlsx" -WorksheetName "addresses"
$ipAddressNamesFromExcel = $ipTable | Select-Object -expandproperty "Name"
$existingAddresses = Get-FMAddress -Connection $Connection -verbose -fields "name" | Select-Object -expandproperty name

$missingAddresses = $ipAddressNamesFromExcel | Where-Object { $_ -notin $existingAddresses } | Sort-Object -Unique
Write-PSFMessage -Level Host "$($existingAddresses.count) Adresses found in Forti, $($ipAddressNamesFromExcel.count) within Excel, missing $($missingAddresses.count)"
$newFMAddresses = @()
foreach ($newAddress in $missingAddresses) {
    Write-PSFMessage -Level Host "Create address object: $newAddress"
    $newFMAddresses += New-FMObjAddress -Name "$newAddress" -Type ipmask -Subnet "$newAddress"  -Comment "Created ByScript"
}
Lock-FMAdom -Connection $connection -RevisionNote "Changes by API"
try {
    $newFMAddresses | add-fmaddress -connection $connection
    Publish-FMAdomChange -Connection $connection
}
catch {
    Write-PSFMessage -Level Warning "$_"
}
finally {
    UnLock-FMAdom -Connection $connection
}
Disconnect-FM -connection $Connection

If you need an overview of the existing commands use

# List available commands
Get-Command -Module FortiManager

Connect to an Analyzer instance and search the logs for a specific device, last 1 hour, only specific fields:

$faCon = Connect-FM -Credential (Get-Secret 'FortiAnalyzer') -Url myanalyzer.mycompany.com -Adom 'root' -Type Analyzer
$logResults=Search-FMALog -Device CompFW001 -Logtype traffic -Last ([timespan]::FromHours(1)) -Fields action,policyid,policyname,srcip,dstip

everything else is documented in the module itself.

Roadmap

New features will be added if any of my scripts need it ;-)

I cannot guarantee that no breaking change will occur as the development follows my internal DevOps need completely. Likewise I will not insert full documentation of all parameters as I don't have time for this copy&paste. Sorry. But major changes which classify as breaking changes will result in an increment of the major version. See Changelog for information regarding breaking changes.

See the open issues for a list of proposed features (and known issues).

If you need a special function feel free to contribute to the project.

Contributing

Contributions are what make the open source community such an amazing place to be learn, inspire, and create. Any contributions you make are greatly appreciated. For more details please take a look at the CONTRIBUTE document

Short stop:

1. Fork the Project
2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
3. Commit your Changes (git commit -m 'Add some AmazingFeature')
4. Push to the Branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Limitations

• The module works on the ADOM level as this is the only permission set I've been granted
• Maybe there are some inconsistencies in the docs, which may result in a mere copy/paste marathon from my other projects

License

Distributed under the GNU GENERAL PUBLIC LICENSE version 3. See LICENSE.md for more information.

Contact

Project Link: https://github.com/Callidus2000/FortiManager

Acknowledgements

• Friedrich Weinmann for his marvelous PSModuleDevelopment and psframework