graphiant.naas.graphiant_security_policy module – Manage device security policy rulesets and zone pair attachments

Note

This module is part of the graphiant.naas collection (version 26.6.0).

You might already have this collection installed if you are using the ansible package. It is not included in ansible-core. To check whether it is installed, run ansible-galaxy collection list.

To install it, use: ansible-galaxy collection install graphiant.naas. You need further requirements to be able to use this module, see Requirements for details.

To use it in a playbook, specify: graphiant.naas.graphiant_security_policy.

New in graphiant.naas 26.6.0

Synopsis 

Configure or delete device-level security policy rulesets under edge.trafficPolicy.securityRulesets.
Attach or detach a named ruleset on zone pairs under edge.trafficPolicy.zones.
Reads a structured YAML config file and builds the raw device-config payload in Python.
The configure workflow applies rulesets (operation=configure) and attaches them to zone pairs (operation=attach_to_zone_pairs). The deconfigure workflow clears zone pair references (operation=detach_from_zone_pairs) and deletes listed rulesets (operation=deconfigure).
Configure is idempotent: compares intended rulesets to existing device state and skips push when already matched.
Deconfigure deletes only the rulesets listed in the YAML by setting ruleset: null per ruleset key.
Under configure, set state: absent on a ruleset or individual rule in YAML to delete only that object (sends ruleset: null or rule: null in the payload). Omitted state means present.
Rule action (per rule): accept, reject, inspect, or drop. Ruleset implicitRuleAction (catch-all for unmatched traffic): accept or reject only. Values are normalized to lowercase strings in the device-config payload.
Each rule supports one primary match type: application (applicationBuiltin / applicationCustom) or network/L4 (ipProtocol, sourceNetwork, destinationNetwork, ports). Combining both in the same rule is rejected.
You cannot change a rule’s primary match type in place (for example, from applicationBuiltin to ipProtocol / destinationNetwork, or the reverse). The device API merges rule updates and leaves stale match criteria. Delete the rule (state: absent) and add a new rule with the desired match instead.
Attach/detach operations compare each listed zone pair’s ruleset reference to the device and skip when unchanged.
With ansible-playbook --check, writes are skipped but changed reflects whether an apply would update at least one device. Use --diff to preview details.diff_plan and Ansible diff.

Requirements 

The below requirements are needed on the host that executes this module.

python >= 3.7
graphiant-sdk >= 25.12.1

Parameters 

Parameter	Comments
access_token string	Bearer token for API authentication (for example, from `graphiant login`, which opens a browser for sign-in (SSO or non-SSO) and retrieves the token). If not passed as a module argument, the collection reads `GRAPHIANT_ACCESS_TOKEN` (set after `graphiant login` when you `source ~/.graphiant/env.sh`). When a bearer token is present (module argument or environment), it takes precedence over `username` and `password`. If no valid token is available, the module authenticates with `username` and `password` when both are supplied.
detailed_logs boolean	Enable detailed logging. Choices: `false` ← (default) `true`
host aliases: base_url string / required	Graphiant portal host URL for API connectivity. Example: “https://api.graphiant.com”
operation string	Specific operation to perform. `configure` creates/updates rulesets listed under `securityRulesets`. `deconfigure` deletes listed rulesets by setting `ruleset=null`. `attach_to_zone_pairs` sets `edge.trafficPolicy.zones` from the YAML `zones` list (each entry uses `fromZone`, `toZone`, and `ruleset`). `detach_from_zone_pairs` clears ruleset references on each zone pair listed under `zones`. Choices: `"configure"` `"deconfigure"` `"attach_to_zone_pairs"` `"detach_from_zone_pairs"`
password string	Graphiant portal password for authentication. Required for password-based login when no valid bearer token is available from `access_token` or `GRAPHIANT_ACCESS_TOKEN`.
security_policy_config_file string / required	Path to the security policy YAML file. Can be an absolute path or relative to the configured config_path. Expected top-level key is `SecurityPolicyObject` (list of devices). Each device may define `securityRulesets` and/or `zones` in the same file.
state string	Desired state for security policy rulesets. `present` maps to `configure` when `operation` is omitted. `absent` maps to `deconfigure` when `operation` is omitted. Choices: `"present"` ← (default) `"absent"`
username string	Graphiant portal username for authentication. Required for password-based login when no valid bearer token is available from `access_token` or `GRAPHIANT_ACCESS_TOKEN`.

Attributes 

Attribute	Support	Description
check_mode	Support: full In check mode, no configuration is pushed to devices, but the module still reads current device state to determine whether changes would be made. Payloads that would be pushed are logged with a `[check_mode]` prefix.	Supports check mode.
diff_mode	Support: full When the playbook runs with `--diff` and a device would change, the module returns a `diff` dictionary (`before` / `after` strings). Structured entries are also in `details.diff_plan`. Ruleset diffs list only changed rules under `rules` (plus `_meta` when ruleset metadata changes).	Supports Ansible’s `--diff` for pending security policy updates.

Notes 

Note

One YAML file may define both securityRulesets and zones. configure/deconfigure read securityRulesets only; attach_to_zone_pairs/detach_from_zone_pairs read zones only. Run both steps for a full security policy lifecycle, or use the sample playbook tags configure and deconfigure.
Configuration files support Jinja2 templating syntax for dynamic configuration generation.
Check mode (--check) reads live device state, skips writes, sets changed from whether an apply would update at least one device, and logs would-be payloads with a [check_mode] prefix when detailed_logs is enabled.
Diff mode (--diff) adds Ansible diff (before / after strings) and details.diff_plan. Ruleset entries list only changed rules under rules (plus _meta when ruleset metadata changes). Zone pair attach/detach diffs show per-pair ruleset references under zones.

Examples 

- name: Configure device-level security policy rulesets
  graphiant.naas.graphiant_security_policy:
    operation: configure
    security_policy_config_file: "sample_device_security_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

- name: Attach security ruleset to zone pairs
  graphiant.naas.graphiant_security_policy:
    operation: attach_to_zone_pairs
    security_policy_config_file: "sample_device_security_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true

# Preview pending changes without pushing (check mode)
- name: Preview security policy configure (dry run)
  graphiant.naas.graphiant_security_policy:
    operation: configure
    security_policy_config_file: "sample_device_security_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
    detailed_logs: true
  check_mode: true
  register: security_policy_preview

# Preview per-rule diffs (run playbook with --diff or set diff: true on the task)
- name: Preview security policy rule changes
  graphiant.naas.graphiant_security_policy:
    operation: configure
    security_policy_config_file: "sample_device_security_policies.yaml"
    host: "{{ graphiant_host }}"
    username: "{{ graphiant_username }}"
    password: "{{ graphiant_password }}"
  diff: true
  register: security_policy_diff
  # details.diff_plan[].before/after.securityRulesets.<name>.rules.<seq> — changed rules only

Return Values 

Common return values are documented here, the following are the fields unique to this module:

Key	Description
changed boolean	Whether the operation would push config to at least one device. In check mode (`--check`), no configuration is pushed, but `changed` reflects whether changes would be made. Returned: always
configured_devices list / elements=string	Device names where configuration was pushed (when changed=true). Returned: when supported
details dictionary	Raw manager result details (includes `diff_plan`, configured/skipped device lists). Each `diff_plan` entry has `device`, `branch` (for example `edge.trafficPolicy.securityRulesets` or `edge.trafficPolicy.zones`), and normalized `before` / `after` snapshots. Ruleset branches list only changed rules under `rules`; ruleset metadata changes appear under `_meta`. Zone pair branches list `ruleset` and `tcpProtection` per pair. Returned: when supported
diff dictionary	Ansible diff output when the playbook runs with `--diff` and at least one device would change. Built from `details.diff_plan` as JSON `before` / `after` strings per device and branch. Returned: when diff mode is enabled and `details.diff_plan` is non-empty
msg string	Result message (includes detailed logs when enabled). Returned: always
operation string	The operation performed. Returned: always
security_policy_config_file string	The security policy config file used for the operation. Returned: always
skipped_devices list / elements=string	Device names that were skipped because desired state already matched. Returned: when supported

Authors

Graphiant Team (@graphiant)

graphiant.naas.graphiant_security_policy module – Manage device security policy rulesets and zone pair attachments

Synopsis

Requirements

Parameters

Attributes

Notes

Examples

Return Values