Skip to content

Commit ba87973

Browse files
zachcamara-hpezachcamara-hpe
committed
Merge branch 'docs/july22-code-examples' into development
2 parents 4c5ae96 + 69ebf44 commit ba87973

6 files changed

Lines changed: 883 additions & 29 deletions

File tree

‎docs/source/examples/generate_preconfig.rst‎

Lines changed: 17 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -3,12 +3,19 @@
33
44
.. important::
55

6-
The following example is more complex code than the other examples,
6+
The following example is more complex code than the general examples,
77
generating data and interacting with Orchestrator. Using and
88
modifying these examples requires a greater understanding of python
99
functions, handling variables, and additional tools such as Jinja.
1010

1111

12+
.. note::
13+
14+
The code referenced in this document and all published examples
15+
with pyedgeconnect are available from the GitHub repository within the
16+
`examples <https://https://github.com/SPOpenSource/edgeconnect-python/tree/main/examples>`_
17+
folder
18+
1219
Generate EdgeConnect Preconfig
1320
------------------------------
1421

@@ -154,17 +161,19 @@ Additional availble runtime arguments are as follows:
154161
- ``-o`` or ``--orch``
155162
- Type: String
156163
- Desc: Specify the Orchestrator IP or FQDN
157-
- Example values: ``10.100.1.90`` or ``orchestrator.<company>.com``
164+
- Example values: ``192.0.2.100`` or ``orchestrator.<company>.com``
158165
- Default value: ``None``
159166
- ``-u`` or ``--upload``
160167
- Type: Boolean
161-
- Desc: Upload the rendered YAML preconfig to Orchestrator
162-
- Accepted values: ``True`` or ``False``
168+
- Desc: Upload the rendered YAML preconfig to Orchestrator.
169+
Including the ``-u`` will translate to ``True``, no option will
170+
default to ``False``
163171
- Default value: ``False``
164172
- ``-aa`` or ``--autoapply``
165173
- Type: Boolean
166-
- Desc: Auto-apply the YAML preconfig on Orchestrator to a discovered appliance
167-
- Accepted values: ``True`` or ``False``
174+
- Desc: Auto-apply the YAML preconfig on Orchestrator to a
175+
discovered appliance. Including the ``-aa`` will translate to
176+
``True``, no option will default to ``False``
168177
- Default value: ``False``
169178
- ``-j`` or ``--jinja``
170179
- Type: String
@@ -209,7 +218,8 @@ Orchestrator API calls
209218
^^^^^^^^^^^^^^^^^^^^^^^^^^
210219

211220
The two API calls to Orchestrator (outside of authentication) are
212-
``validate_preconfig`` and ``create_preconfig``.
221+
:func:`pyedgeconnect.Orchestrator.validate_preconfig` and
222+
:func:`pyedgeconnect.Orchestrator.create_preconfig`.
213223

214224
The ``validate_preconfig`` function sends the preconfig YAML text to
215225
Orchestrator and will either return a success (HTTP 200 OK) or if

‎docs/source/examples/index.rst‎

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -3,8 +3,10 @@ Example Code from Repository
33
============================
44

55
All examples documented in this section are available from the
6-
GitHub repository within the ``examples`` folder:
7-
https://github.com/SPOpenSource/edgeconnect-python/tree/main/examples
6+
GitHub repository within the
7+
`examples <https://https://github.com/SPOpenSource/edgeconnect-python/tree/main/examples>`_
8+
folder:
9+
810

911
Example script documentation and instructions
1012

@@ -13,4 +15,5 @@ Example script documentation and instructions
1315

1416
auth_example
1517
basic_examples
16-
generate_preconfig
18+
generate_preconfig
19+
upload_security_policy

‎docs/source/examples/upload_security_policy.rst‎

Lines changed: 296 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,296 @@
1+
.. upload_security_policy:
2+
3+
4+
.. important::
5+
6+
The following example is more complex code than the general examples,
7+
generating data and interacting with Orchestrator. Using and
8+
modifying these examples requires a greater understanding of python
9+
functions, handling variables, and conforming source data to your
10+
own environment.
11+
12+
Updating the security policy of an EdgeConnect, especially with
13+
automation, should be treated with caution as a bad firewall policy
14+
could allow unwanted traffic or block unintended production traffic.
15+
This code example is not meant to check the intent of any rules,
16+
simply show how policy can be uploaded in an automated fashion.
17+
18+
.. note::
19+
20+
The code referenced in this document and all published examples
21+
with pyedgeconnect are available from the GitHub repository within the
22+
`examples <https://https://github.com/SPOpenSource/edgeconnect-python/tree/main/examples>`_
23+
folder:
24+
25+
Upload EdgeConnect Security Policy
26+
----------------------------------
27+
28+
This example uses a CSV file as source data to generate a security
29+
policy for EdgeConnect. The security policy can be uploaded to a net-new
30+
Template Group to later be applied to multiple appliances or pushed
31+
directly to a single appliance.
32+
33+
The client running the script communicates with Orchestrator, and
34+
Orchestrator in turn passes the data to the Edge Connect appliance if
35+
pushing policy directly to an appliance.
36+
37+
EdgeConnect Firewall Zone Behavior
38+
==================================
39+
40+
Prior to Orchestrator 9+, Zone firewall rules are required for the
41+
source Zone to the assigned Zone of the overlay the traffic will match
42+
into as well as rules for egressing the overlay Zone to the final
43+
destination Zone.
44+
45+
For example:
46+
47+
Traffic is sourced from a LAN-side Zone of "Users", crossing into
48+
the Overlays, all of which have a zone of "Fabric", and finally when
49+
reaching the far-end, egressing to a zone of "Protected."
50+
51+
For a rule to allow ``192.0.2.0/24`` from ``Users`` to ``198.51.100.0/24`` in
52+
``Protected`` there would be two rules required:
53+
54+
.. list-table::
55+
:header-rows: 1
56+
57+
* - From Zone
58+
- To Zone
59+
- Source IP
60+
- Dest IP
61+
* - Users
62+
- Fabric
63+
- 192.0.2.0/24
64+
- 198.51.100.0/24
65+
* - Fabric
66+
- Protected
67+
- 192.0.2.0/24
68+
- 198.51.100.0/24
69+
70+
For Orchestrator 9+, on the Firewall Zone Secuirty Policies page
71+
(``Configuration -> Overlays & Security -> Security -> Firewall Zone Security Policies``)
72+
there is a toggle for ``New Firewall Zoning``. When enabled, this allows
73+
rules to account for end-to-end behavior and no longer requires zones
74+
for the overlays. For the same use case there would be a single rule:
75+
76+
.. list-table::
77+
:header-rows: 1
78+
79+
* - From Zone
80+
- To Zone
81+
- Source IP
82+
- Dest IP
83+
* - Users
84+
- Protected
85+
- 192.0.2.0/24
86+
- 198.51.100.0/24
87+
88+
89+
Python Script & Orchestrator API calls
90+
======================================
91+
92+
The script will first check in with Orchestrator to pull information
93+
to correlate object id's to the friendly names used in the source data
94+
such as appliance hostname, zone names, and overlay names.
95+
96+
.. note::
97+
98+
Zones referenced in the policy must already exist in Orchestrator.
99+
While there are pyedgeconnect functions to create Zones, this
100+
example does not create previously undefined Zones from the ruleset
101+
in Orchestrator.
102+
103+
The example data included in the file ``security_policy.csv`` must
104+
be updated accordingly for your environment referencing appropriate
105+
security zones, rule priorites, merge settings and/or default
106+
logging levels where applicable.
107+
108+
IP Ranges used in sample rules follow RFC 5735 as example ranges
109+
110+
For each rule specified, add match criteria to the ruleset with the
111+
specified priority and within the appropriate zone pair.
112+
113+
Once the ruleset is complete, the security map will be installed to the
114+
specified new Template Group or appliance directly per the runtime
115+
arguments.
116+
117+
.. note::
118+
119+
To reference all possible match criteria fields, get existing
120+
security policy from an EdgeConnect to see the corresponding JSON.
121+
This can be proxied through Orchestrator with
122+
:func:`pyedgeconnect.Orchestrator.appliance_get_api` while
123+
specifying the nePk of the appliance to the endpoint
124+
``/securityMaps``, or connecting directly to the appliance with
125+
:func:`pyedgeconnect.EdgeConnect.get_appliance_security_policy_map`
126+
127+
128+
Runtime arguments
129+
^^^^^^^^^^^^^^^^^
130+
131+
The python script has multiple runtime arguments defined. The primary
132+
required argument is ``-c`` or ``--csv`` to specify the CSV file to be
133+
read as source data for generating the security policy.
134+
135+
The destination of the rules will depend on one of the two following
136+
options:
137+
138+
* Use ``-a`` or ``--appliance`` to specify the appliance hostname to
139+
apply the policy to directly
140+
* Use ``-tg`` or ``--templategroup`` to specify the name of a new
141+
Template Group to be created with the security policy selected
142+
143+
Running the script and pushing rules to an appliance named MY-APPLIANCE-01:
144+
145+
.. code-block:: bash
146+
147+
python upload_security_policy.py -c security_policy.csv -a MY-APPLIANCE-01
148+
149+
Additional availble runtime arguments are as follows:
150+
151+
- ``-dll`` or ``--denyloglevel``
152+
- Type: Integer
153+
- Desc: Specify the Log Level for deny all log events
154+
- Example values: ``0`` for none or ``8`` for debug
155+
- Default value: ``2``
156+
- ``-m`` or ``--merge``
157+
- Type: Boolean
158+
- Desc: Merge rules with existing rules on appliance, will overwrite
159+
rules with same priority value in a zone pair. Including the
160+
``-m`` will translate to ``True``, no option will default to
161+
``False``
162+
- Default value: ``False``
163+
- ``-o`` or ``--orch``
164+
- Type: String
165+
- Desc: Specify the Orchestrator IP or FQDN
166+
- Example values: ``192.0.2.100`` or ``orchestrator.<company>.com``
167+
- Default value: ``None``
168+
169+
Running the script and pushing rules to a Template Group named
170+
Group-Sec-Policy set to merge and default log level of 3:
171+
172+
.. code-block:: bash
173+
174+
python upload_security_policy.py -c security_policy.csv -tg Group-Sec-Policy -m -dll 3
175+
176+
177+
CSV File / Source Data for Variables
178+
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
179+
180+
In this example the source data for generating a security ruleset is a
181+
CSV file. The variables referenced in the match criteria of the python
182+
correspond to the headers in the CSV file.
183+
184+
.. important::
185+
186+
The included CSV file has headers for all possible match criteria
187+
as of Orchestrator 9.1. As new match criteria is introduced it may
188+
be necessary to add columns in the CSV and if-statements in the
189+
python to add appropriate criteria for new options. Similarly,
190+
columsn for paramters that are unused in the rules are not necessary
191+
to be present in the CSV file.
192+
193+
In the opposite direction, features such as Address or Service
194+
groups were only introduced in Orchestrator 9.1, and would not apply
195+
to policy for a pre-9.1 environment.
196+
197+
.. note::
198+
199+
* EdgeConnect 8.x only supports ~600 rules
200+
* This script only supports a maximum of 1000 rules
201+
* Rule priorities for appliance ruleset should be in the range of 25000+
202+
* Rule priorities for template group policies should be between 1000-9999
203+
204+
Below is a reference for the values currently supported for the CSV file.
205+
206+
The columns ``rule_priority``, ``action``, ``src_zone``, and
207+
``dst_zone`` are required, other headers are optional.
208+
209+
* ``rule_priority``: The priority of the rule in the zone pair
210+
* ``action``: Allow or deny matching traffic, e.g. ``allow`` or ``deny``
211+
* ``src_zone``: Source Firewall Zone, e.g. ``Corp``
212+
* ``dst_zone``: Destination Firewall Zone, e.g. ``Public``
213+
* ``acl``: Name of ACL to match
214+
* ``src_ip``: Source IP Address to match, e.g. ``192.0.2.0/24``
215+
* ``dst_ip``: Destination IP Address to match, e.g. ``8.8.8.8/32``
216+
* ``either_ip``: Source or Destination IP Address to match
217+
* ``src_addrgrp_groups``: Source Address Group
218+
* ``dst_addrgrp_groups``: Destination Address Group
219+
* ``either_addrgrp_groups``: Source or Destination Address Group
220+
* ``protocol``: Protocol to match, e.g. ``ip``, ``icmp``
221+
* ``src_port``: Source IP Port to match, e.g. ``162``
222+
* ``dst_port``: Destination IP Port to match, e.g. ``443``
223+
* ``vlan``: Interface to match on, e.g. ``lan0``, ``lan0.10``
224+
* ``application``: Application name to match (built-in or user-defined)
225+
* ``app_group``: Application group name to match (built-in or user-defined)
226+
* ``dscp``: DSCP marking to match, e.g. ``af11``
227+
* ``src_dns``: Source DNS to match
228+
* ``dst_dns``: Destination DNS to match, e.g. ``*google.com``
229+
* ``either_dns``: Source or Destination DNS to match
230+
* ``src_geo``: Source geo to match, e.g. ``Brazil``
231+
* ``dst_geo``: Destination geo to match, e.g. ``United States``
232+
* ``either_geo``: Source or Destination geo to match
233+
* ``src_service``: Source Address Map name to match
234+
* ``dst_service``: Destination Address Map name to match
235+
* ``either_service``: Source or Destination Address Map name to match
236+
* ``tbehavior``: Identified traffic behavior, e.g. ``Idle``, ``Voice``,
237+
``Video_Conferencing``
238+
* ``overlay``: Overlay name to match
239+
* ``internet``: ``Fabric`` or ``Internet``
240+
* ``logging``: Enable logging for rule with ``enable``, defaults to
241+
``disable``
242+
* ``logging_priority``: Loggig priority level for rule. Defaults to ``0``
243+
244+
Logging levels translate as follows:
245+
246+
.. list-table::
247+
:header-rows: 1
248+
249+
* - Numeric Level
250+
- Log Level
251+
* - 0
252+
- None
253+
* - 1
254+
- Emergency
255+
* - 2
256+
- Alert
257+
* - 3
258+
- Critical
259+
* - 4
260+
- Error
261+
* - 5
262+
- Warning
263+
* - 6
264+
- Notice
265+
* - 7
266+
- Info
267+
* - 8
268+
- Debug
269+
270+
Orchestrator API calls
271+
^^^^^^^^^^^^^^^^^^^^^^^^^^
272+
273+
The API calls to Orchestrator (outside of authentication) used in this
274+
example are:
275+
276+
* :func:`pyedgeconnect.Orchestrator.get_appliances`
277+
* Retrieves all appliances to correlate provided appliance name to
278+
appliance id for pushing security rules to appliance
279+
* :func:`pyedgeconnect.Orchestrator.get_all_overlays_config`
280+
* Retrieves all overlays to correlate overlay names in policy source
281+
data to overlay ids
282+
* :func:`pyedgeconnect.Orchestrator.get_all_template_groups`
283+
* Retrieves all template groups to make sure new template group name
284+
is unique, will otherwise exit
285+
* :func:`pyedgeconnect.Orchestrator.get_zones`
286+
* Retrieves all zones to correlate zone names in policy source data
287+
to zone ids
288+
* :func:`pyedgeconnect.Orchestrator.create_template_group`
289+
* Creates new template group in Orchestrator
290+
* :func:`pyedgeconnect.Orchestrator.select_templates_for_template_group`
291+
* Selects active templates in template group, in this case, security
292+
policy
293+
* :func:`pyedgeconnect.Orchestrator.appliance_post_api`
294+
* Sends a POST to appliance ECOS API endpoint, in this case to
295+
``/securityMaps`` to push security policy directly to appliance
296+
through an Orchestrator API endpoint as passthrough.

0 commit comments

Comments
 (0)