Skip to content

OASIS OpenC2 TC: A prototype implementation in R to transform between OpenC2 and Cisco ACL formats. The adapter supports access control list (ACL) management. https://github.com/oasis-open/openc2-iosacl-adapter

License

Notifications You must be signed in to change notification settings

oasis-open/openc2-iosacl-adapter

Repository files navigation

README

OASIS TC Open Repository: openc2-iosacl-adapter

This GitHub public repository (https://github.com/oasis-open/openc2-iosacl-adapter/) was created at the request of the OASIS Open Command and Control (OpenC2) TC as an OASIS TC Open Repository to support development of open source resources related to Technical Committee work.

While this TC Open Repository remains associated with the sponsor TC, its development priorities, leadership, intellectual property terms, participation rules, and other matters of governance are separate and distinct from the OASIS TC Process and related policies.

All contributions made to this TC Open Repository are subject to open source license terms expressed in the MIT License. That license was selected as the declared Applicable License when the TC Open Repository was created.

As documented in Public Participation Invited, contributions to this OASIS TC Open Repository are invited from all parties, whether affiliated with OASIS or not. Participants must have a GitHub account, but no fees or OASIS membership obligations are required. Participation is expected to be consistent with the OASIS TC Open Repository Guidelines and Procedures, the open source LICENSE designated for this particular repository, and the requirement for an Individual Contributor License Agreement that governs intellectual property.

Statement of Purpose

  • To demonstrate an adapter translating OpenC2 commands to Cisco ACL format (syntax) for Access Control Lists (ACLs) management, and

  • Provide an R code base to facilitate other prototype efforts,

openc2-iosacl-adapter

The openc2-iosacl-adapter is a software tool (Proof of Concept) written in R for parsing, translating, and executing OpenC2 commands to CISCO devices running IOS (Internetwork Operating System) and IOS-XE, and support Access Control Lists (ACL). All the activity, response codes, and messages are stored in a database.

The repository contains source code (multiple interdependent R files) here, a sample actuator (consumer) schema/strucure file with recommended information for inclusion here (this is omitted if we connect the openc2-iosacl-adapter with an orchestrator), OpenC2 sample commands for experimentation here and here, and some other folders containing Cisco-related details to assist in the configuration of the actuator. The tool can be used as a command-line tool or integrated with other applications, such as OpenC2 orchestrator or proxy.

Note: The tool participated in testing conformance and interoperability at the OpenC2 Plugfest on January 27 and 28 2020. You can find more information about the use case tested and the lab HERE.

Conformance

The openc2-iosacl-adapter conforms with the OpenC2 Language Specification v1.0 and the Stateless Packet Filtering Specification (SLPF) v1.0

Quickstart

Important Note: The openc2-iosacl-adapter has been checked in devices that run IOS and IOS-XE. Even though this implementation is mainly written in R, for the execution (communication) of the commands we use the "reticulate" library that provides an interface to Python for the simple reason that we use the "netmiko" Python library to execute the commands. Part of the object or dictionary for specifying the connection details with netmiko is providing the device and the version of OS the commands will be executed. In our case, this is "cisco_ios" or "cisco_xe". Depending on your implementations the following changes should be done (the default is cisco_ios - you don't need to change if your device runs Cisco IOS).

Change the parameter "device_type" to "cisco_xe" or "cisco_ios". This appears in the files openc2_slpf_cisco_ios_main.R and openc2_slpf_cisco_ios_transport.R

An example: connection <- netmiko$ConnectHandler(device_type = "cisco_xe", ip = consumer$hostname, username = consumer$username, password = consumer$password, port = consumer$port)

OR

Replace the files openc2_slpf_cisco_ios_main.R and openc2_slpf_cisco_ios_transport.R from the folder "code" with the ones that are provided in its subfolder "IOS-XE".

If certificates are prefered for authentication, instead of passwords then the parameter "password" should be replaced by the following parameters: use_keys = "True" key_file = "private_key"

An example: connection <- netmiko$ConnectHandler(device_type = "cisco_xe", ip = consumer$hostname, username = consumer$username, port = consumer$port, use_keys = "True", key_file = "private_key")

"key_file" is the private key stored in your device. The public key should be stored on the ssh server (Cisco device).

The main file for executing OpenC2 commands is openc2_iosacl_adapter.R

"Rscript openc2_iosacl_adapter.R -- help" will show all the available options

-o OPENC2, --openc2=OPENC2
                OpenC2 command in JSON - The command needs to be given as a single line enclosed in single quotation marks

        -f FILE, --file=FILE
                file including one or more OpenC2 commands in JSON - optimally, full path should be given

        -a ACTUATORS, --actuators=ACTUATORS
                consumer/actuator information file

        -h, --help
                Show this help message and exit

Execute an OpenC2 command

Execute "Rscript openc2_iosacl_adapter.R -o *'OpenC2_command_enclosed_in_single_quotations'* -a *actuators information file*

Prerequisites

  1. R - https://www.r-project.org/

  2. Python 2 or 3 - https://www.python.org/

  3. Netmiko - "pip install netmiko" or check here

  4. Configuration file including relevant actuator/consumer information. You can find an example file that references the appropariate structure here (this is omitted if we connect the openc2-iosacl-adapter with an orchestrator).

For example:

      { 
         "asset_id":"10",
         "description":"OSLO-UIO-cisco-edge-router-slpf-ingress",
         "network":{ 
            "interface":"WAN",
            "hostname":"10.10.10.1",
            "port":8080,
            "username":"user1",
            "password":"12345",
            "direction":"ingress",
            "acl_id":"wan_inbound",
            "acl_type":"ipv4"
         }
      }

Required name/value pairs for communicating with an actuator using the actuators.json file are:

  1. asset_id
  2. network
    • hostname
    • port
    • username
    • password
    • acl_id
    • acl_type

Supported Actions, Targets, Arguments, and Actuator Specifiers

Actions

ID Name Description
3 query Initiate a request for information. Used to communicate the supported options and determine the state or settings
6 deny Prevent traffic or access
8 allow Permit traffic or access
16 update Instructs the Actuator to update its configuration by retrieving and processing a configuration file and update
20 delete Remove an access rule

Targets

ID Name Type Description
9 features Features A set of items such as Action/Target pairs, profiles versions, options that are supported by the Actuator. The Target is used with the query Action to determine an Actuator's capabilities
10 file File Properties of a file
15 ipv4_connection IPv4-Connection A network connection as specified by a five-tuple (IPv4)
16 ipv6_connection IPv6-Connection A network connection as specified by a five-tuple (IPv6)

The semantics/ requirements as they pertain to common targets:

  • ipv4_connection
    • If the protocol = ICMP, the five-tuple is: src_addr, dst_addr, icmp_type, icmp_code, protocol where the ICMP types and codes are defined in [RFC2780]
    • If the protocol = TCP, UDP or SCTP, the five-tuple is: src_addr, src_port, dst_addr, dst_port, protocol
    • For any other protocol, the five-tuple is: src_addr, unused, dst_addr, unused, protocol
  • ipv6_connection
    • If the protocol = ICMP, the five-tuple is: src_addr, dst_addr, icmp_type, icmp_code, protocol where the ICMP types and codes are defined in [RFC4443]
    • If the protocol = TCP, UDP or SCTP, the five-tuple is: src_addr, src_port, dst_addr, dst_port, protocol
    • For any other protocol, the five-tuple is: src_addr, unused, dst_addr, unused, protocol

Targets Unique to SLPF

ID Name Type Description
1024 rule_number Rule-ID Immutable identifier assigned when a rule is created. Identifies a rule to be deleted

Arguments

ID Name Type # Description
1 start_time Date-Time 0..1 The specific date/time to initiate the Action
2 stop_time Date-Time 0..1 The specific date/time to terminate the Action
3 duration Duration 0..1 The length of time for an Action to be in effect
4 response_requested Response-Type 0..1 The type of Response required for the Action: none and complete

Arguments Unique to SLPF

ID Name Type # Description
1025 persistent Boolean 0..1 Normal operations assume any changes to a device are to be implemented persistently. Setting the persistent modifier to FALSE results in a change that is not persistent in the event of a reboot or restart
1027 insert_rule Rule-ID 0..1 Specifies the identifier of the rule within a list, typically used in a top-down rule list

Actuator Specifiers

ID Name Type # Description
3 asset_id String 0..1 Unique identifier for a particular SLPF

Feautures/Results (Used with "query":"features")

ID Name Type # Description
1 versions Version 0..* List of OpenC2 language versions supported by this Actuator
2 profiles ArrayOf(Nsid) 0..1 List of profiles supported by this Actuator
3 pairs Action-Targets 0..* List of targets applicable to each supported Action

Author

Maintainers

TC Open Repository Maintainers are responsible for oversight of this project's community development activities, including evaluation of GitHub pull requests and preserving open source principles of openness and fairness. Maintainers are recognized and trusted experts who serve to implement community goals and consensus design preferences.

Initially, the associated TC members have designated one or more persons to serve as Maintainer(s); subsequently, participating community members may select additional or substitute Maintainers, by consensus.

The current Maintainers of this TC Open Repository

About OASIS TC Open Repositories

Feedback

Questions or comments about this TC Open Repository's activities should be composed as GitHub issues or comments. If use of an issue/comment is not possible or appropriate, questions may be directed by email to the Maintainer(s) listed above.

Please send general questions about TC Open Repository participation to OASIS Staff at repository-admin@oasis-open.org and any specific CLA-related questions to repository-cla@oasis-open.org.

About

OASIS OpenC2 TC: A prototype implementation in R to transform between OpenC2 and Cisco ACL formats. The adapter supports access control list (ACL) management. https://github.com/oasis-open/openc2-iosacl-adapter

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published

Languages