1.2 JNPL Syntax

JNet Packet Language (JNPL) Wiki

Welcome to the JNet Packet Language (JNPL) Wiki! JNPL is a powerful and flexible language designed for defining and managing network packet processing rules within custom scripts. Whether you're a network engineer, developer, or security analyst, JNPL provides the tools you need to dissect, filter, and handle network traffic with precision.

Introduction

JNet Packet Language (JNPL) is designed to provide robust and expressive capabilities for network packet filtering and processing. Inspired by tools like Wireshark, JNPL allows users to define complex filtering rules, manage IP flows, and handle traffic across multiple network interfaces seamlessly.

Key Features:

Expressive Syntax: Define intricate filtering and processing rules with ease.
CIDR Support: Efficiently filter based on IP address ranges.
Global and Action-Specific Configurations: Manage IP flows globally while handling specific traffic scenarios through actions.
Hashing Mechanisms: Distribute traffic intelligently using customizable hashing modes.
Dynamic Logging: Gain real-time insights into traffic handling with dynamic log statements.

Getting Started

To begin using JNPL, follow these steps:

Installation:
- Download the latest version of JNPL from the official repository.
- Follow the installation instructions provided in the repository's README.
Basic Setup:
- Create a new .jnpl script file.
- Define your filters, IP flow modes, actions, protocols, and hash modes as needed.
Execution:
- Use the JNPL command-line tool to execute your scripts against network captures or live traffic.
- Example:
```
jnpl-runner -f your_script.jnpl -i eth0
```
Documentation:
- Refer to the sections below for detailed syntax and configuration options.

Syntax Overview

JNPL scripts are structured into distinct sections, each serving a specific purpose in the packet processing workflow. The primary sections include:

Filters: Define conditions to select specific network traffic.
IpfMode: Configure global IP flow handling across network interfaces.
Actions: Specify how selected traffic should be processed.
Protocols: Define and configure network protocols.
HashModes: Determine traffic distribution mechanisms.

Each section begins with its type (e.g., filter, IpfMode, action) followed by a name and a block containing relevant attributes and configurations.

Basic Structure:

filter FilterName {
    // Filter conditions
}

IpfMode {
    // IPFMode configurations
}

action ActionName {
    // Action attributes and statements
}

protocol ProtocolName {
    // Protocol-specific configurations
}

HashMode HashModeName {
    // HashMode configurations
}

Core Sections

Filters

Filters are used to select specific network traffic based on various criteria such as IP addresses, ports, protocols, and payload content.

Syntax:

filter FilterName {
    // Filter conditions
}

Example:

filter HTTP_Traffic {
    TCP.dstPort == 80 OR TCP.dstPort == 8080
}

Key Attributes:

Logical Operators: AND, OR, NOT to combine conditions.
Comparison Operators: ==, !=, >, <, >=, <=.
Wildcard and Range Support: For IP addresses and ports.

IpfMode

IpfMode defines global configurations for handling IP flows across specified physical network interfaces. These settings remain active until explicitly deleted.

Syntax:

IpfMode {
    unmatchedFragments = <integer>
    Timeout = <hexadecimal or decimal>
    TablePersist = <TimeoutOnly | LastFragment>
    ClassifyUnmatched = <None | Outer | All>
    ColorInherit = <true | false>
    RxPort = (<port range>)
}

Example:

IpfMode {
    unmatchedFragments = 1
    Timeout = 0x1F4        // 500 in decimal
    TablePersist = TimeoutOnly
    ClassifyUnmatched = All
    ColorInherit = true
    RxPort = (0..3)
}

IpfMode {
    unmatchedFragments = 2
    Timeout = 0x258        // 600 in decimal
    TablePersist = LastFragment
    ClassifyUnmatched = None
    ColorInherit = false
    RxPort = (4..7)
}

Attributes Explained:

unmatchedFragments: Number of unmatched fragments to handle.
Timeout: Flow timeout value (in hex or decimal).
TablePersist: Persistence strategy for the IPF table.
ClassifyUnmatched: Handling of unmatched packets.
ColorInherit: Whether to inherit color from parent flows.
RxPort: Physical network interface ports for reception.

Actions

Actions define how selected traffic should be processed, including logging, distribution, slicing, and tagging.

Syntax:

action ActionName {
    Priority = <integer>
    Color = <32-bit hex value>
    ColorMask = <32-bit hex value>
    Slice = <start:end>
    TxPort = <port number>
    DestinationPort = <port number>
    Tag = <identifier>
    TxMetaData = <MetadataType>
    
    filter <FilterName>
    
    log "<log message>"
    
    distribute = (<buffer range>) based on <HashModeName>
}

Example:

action ConfigureCriticalTraffic {
    Priority = 1
    Color = 0xFF0000
    ColorMask = 0x00FFFFFF
    Slice = 12:64
    TxPort = 0
    DestinationPort = 8080
    Tag = Critical
    TxMetaData = TimeStamp

    filter COMBINED_FILTER

    log "Assigned traffic to Critical IPFMode for filter ${Filter.Name}"
    
    distribute = (0..3) based on Hash5Tuple
}

Key Attributes:

Priority: Sets the action's priority level.
Color & ColorMask: Define color coding for visual identification.
Slice: Specifies byte range of the packet payload to process.
TxPort: Physical network interface port for transmission.
DestinationPort: TCP/UDP destination port number.
Tag: Assigns a tag for classification.
TxMetaData: Specifies metadata to transmit (e.g., TimeStamp).
filter: Associates a filter with the action.
log: Logs a message, utilizing dynamic properties.
distribute: Distributes traffic across specified buffers using a defined HashMode.

Protocols

Protocols define and configure network protocols that JNPL will recognize and handle.

Syntax:

protocol ProtocolName {
    // Protocol-specific configurations
}

Example:

protocol TCP {
    // TCP-specific configurations
}

protocol UDP {
    // UDP-specific configurations
}

Key Points:

Define sub-protocols (e.g., IPv4, IPv6) within parent protocols.
Configure protocol-specific settings as needed.

HashModes

HashMode determines how traffic is distributed across processing buffers, enhancing load balancing and efficiency.

Syntax:

HashMode HashModeName {
    Priority = <integer>
    Encapsulation = <list>
    Algorithm = <AlgorithmType>
    Key = <hexadecimal>
    Tag = <identifier>
}

Example:

HashMode Hash5Tuple {
    Priority = 5
    Encapsulation = VLAN,MPLS
    Algorithm = CRC32
    Key = 0xABCDEF
    Tag = VlanTag
}

HashMode Hash3TupleGTPv1v2Sorted {
    Priority = 10
    Encapsulation = VLAN
    Layer3Type = IPv4,IPv6
    Layer4Type = TCP,UDP
    Algorithm = SHA256
}

Attributes Explained:

Priority: Determines the hashing priority.
Encapsulation: Specifies encapsulation types (e.g., VLAN, MPLS).
Algorithm: Hashing algorithm used (e.g., CRC32, SHA256).
Key: Unique key for the hash function.
Tag: Assigns a tag for identification.

Examples

Basic Example

A simple JNPL script that filters HTTP traffic and assigns it to a critical action.

// Define a filter for HTTP traffic
filter HTTP_Traffic {
    TCP.dstPort == 80 OR TCP.dstPort == 8080
}

// Define a hash mode for distribution
HashMode SimpleHash {
    Priority = 1
    Encapsulation = VLAN
    Algorithm = CRC32
    Key = 0x123456
    Tag = SimpleTag
}

// Define a global IPFMode configuration
IpfMode {
    unmatchedFragments = 1
    Timeout = 0x1F4        // 500 in decimal
    TablePersist = TimeoutOnly
    ClassifyUnmatched = All
    ColorInherit = true
    RxPort = (0..3)
}

// Define an action to handle critical traffic
action HandleCriticalTraffic {
    Priority = 1
    Color = 0xFF0000
    ColorMask = 0x00FFFFFF
    Slice = 0:100
    TxPort = 0
    DestinationPort = 80
    Tag = Critical
    TxMetaData = TimeStamp

    filter HTTP_Traffic

    log "Critical HTTP traffic detected on filter ${Filter.Name}"
    
    distribute = (0..3) based on SimpleHash
}

Advanced Configuration

A more complex script handling multiple traffic classes with different IPFMode configurations and actions.

// Define combined filter for specific criteria
filter COMBINED_FILTER {
    TCP_SYN_FILTER
    OR TCP_SYN_ACK_FILTER
    OR FRAME_CONTAINS_TRAFFIC
}

// Define hash modes for different traffic distributions
HashMode AdvancedHash {
    Priority = 2
    Encapsulation = VLAN,MPLS
    Algorithm = SHA256
    Key = 0xFEDCBA
    Tag = AdvancedTag
}

// Global IPFMode configurations
IpfMode {
    unmatchedFragments = 1
    Timeout = 0x1F4
    TablePersist = TimeoutOnly
    ClassifyUnmatched = All
    ColorInherit = true
    RxPort = (0..3)
}

IpfMode {
    unmatchedFragments = 2
    Timeout = 0x258
    TablePersist = LastFragment
    ClassifyUnmatched = None
    ColorInherit = false
    RxPort = (4..7)
}

// Define actions for different traffic types
action CriticalTrafficAction {
    Priority = 1
    Color = 0xFF0000
    ColorMask = 0x00FFFFFF
    Slice = 10:50
    TxPort = 0
    DestinationPort = 443
    Tag = Critical
    TxMetaData = TimeStamp

    filter COMBINED_FILTER

    log "Critical traffic matched filter ${Filter.Name}"
    
    distribute = (0..3) based on AdvancedHash
}

action MonitoringAction {
    Priority = 2
    Color = 0x00FF00
    ColorMask = 0xFF00FF00
    Slice = 20:80
    TxPort = 1
    DestinationPort = 22
    Tag = Monitoring
    TxMetaData = TimeStamp

    filter CONVERSATION_FILTER_10_0_0_1_10_0_0_2_ALT

    log "Monitoring traffic matched filter ${Filter.Name}"
    
    distribute = (0..3) based on Hash3TupleGTPv1v2Sorted
}

Best Practices

Consistent Naming: Use clear and consistent names for filters, actions, and hash modes to enhance readability.
Unique Stream Identifiers: Ensure that each StreamId (if used) is unique to avoid conflicts.
Proper Port Configuration: Accurately map RxPort and TxPort to your physical network interfaces.
Efficient Filters: Optimize filter conditions to reduce processing overhead and improve performance.
Documentation: Comment your scripts extensively to explain configurations and actions for future reference.
Validation: Regularly validate your JNPL scripts in a controlled environment before deploying to production.

Reference

Grammar Specifications

IpfMode

<IpfMode> ::= 'IpfMode' '{'
                <IpfModeAttributes>
              '}'

<IpfModeAttributes> ::= <IpfModeAttribute> { <IpfModeAttribute> }

<IpfModeAttribute> ::= 'unmatchedFragments' '=' <integer>
                     | 'Timeout' '=' <hexadecimal | decimal>
                     | 'TablePersist' '=' <'TimeoutOnly' | 'LastFragment'>
                     | 'ClassifyUnmatched' '=' <'None' | 'Outer' | 'All'>
                     | 'ColorInherit' '=' <'true' | 'false'>
                     | 'RxPort' '=' '(' <portRange> ')'

<portRange> ::= <integer> '..' <integer> | <integer>

Action

<action> ::= 'action' <Identifier> '{'
               <ActionAttributes>
             '}'

<ActionAttributes> ::= <ActionAttribute> { <ActionAttribute> }

<ActionAttribute> ::= 'Priority' '=' <integer>
                    | 'Color' '=' <32-bit hex value>
                    | 'ColorMask' '=' <32-bit hex value>
                    | 'Slice' '=' <start:end>
                    | 'TxPort' '=' <portNumber>
                    | 'DestinationPort' '=' <portNumber>
                    | 'Tag' '=' <Identifier>
                    | 'TxMetaData' '=' <MetadataType>
                    | 'filter' '=' <FilterName>
                    | 'log' '=' <string>
                    | 'distribute' '=' '(' <bufferRange> ')' 'based' 'on' <HashModeName>

<bufferRange> ::= <integer> '..' <integer> | <integer>

Filter

<filter> ::= 'filter' <Identifier> '{'
               <FilterConditions>
            '}'

<FilterConditions> ::= <Condition> { <LogicalOperator> <Condition> }

<Condition> ::= <Expression>

<LogicalOperator> ::= 'AND' | 'OR' | 'NOT'

HashMode

<HashMode> ::= 'HashMode' <Identifier> '{'
                 <HashModeAttributes>
              '}'

<HashModeAttributes> ::= <HashModeAttribute> { <HashModeAttribute> }

<HashModeAttribute> ::= 'Priority' '=' <integer>
                      | 'Encapsulation' '=' <list>
                      | 'Algorithm' '=' <AlgorithmType>
                      | 'Key' '=' <hexadecimal>
                      | 'Tag' '=' <Identifier>

Attribute Definitions

Priority: Integer value determining the priority level.
StreamId: Unique identifier for IP flows.
Action: Type of action to perform (e.g., Log, Handle, Monitor).
Color: 32-bit hexadecimal value for color coding.
ColorMask: 32-bit hexadecimal mask for color application.
Slice: Byte range of the packet payload to process (e.g., 12:64).
TxPort: Physical network interface port for transmission.
RxPort: Physical network interface port for reception.
DestinationPort: TCP/UDP destination port number.
Tag: Identifier for classification purposes.
TxMetaData: Metadata to transmit (e.g., TimeStamp).
Filter: Reference to a defined filter.
Log: Log message with optional dynamic properties.
Distribute: Traffic distribution across buffers based on a hash mode.
AlgorithmType: Hashing algorithm (e.g., CRC32, SHA256).
MetadataType: Type of metadata to include (e.g., TimeStamp).

Contributing

We welcome contributions to the JNPL Wiki! Whether you're adding new sections, refining existing content, or reporting issues, your input is invaluable.

How to Contribute:

Fork the Repository:
- Click on the "Fork" button in the top-right corner of the JNPL Wiki repository.

Clone Your Fork:

git clone https://github.com/your-username/jnpl-wiki.git

Create a New Branch:

git checkout -b feature/your-feature-name

Make Your Changes:
- Edit existing pages or add new ones using Markdown.

Commit Your Changes:

git commit -m "Add feature: Your Feature Description"

Push to Your Fork:

git push origin feature/your-feature-name

Open a Pull Request:
- Navigate to your fork on GitHub and click the "Compare & pull request" button.
- Provide a clear description of your changes and submit the pull request.

Guidelines:

Clarity: Ensure your contributions are clear and well-documented.
Consistency: Follow the existing formatting and naming conventions.
Accuracy: Verify the correctness of your additions or modifications.
Respect: Maintain a respectful and collaborative tone in all contributions.

FAQ

Q1: What is JNPL used for?
A1: JNPL is used for defining and managing network packet processing rules, allowing users to filter, dissect, and handle network traffic efficiently within custom scripts.

Q2: How do I define a new filter?
A2: Use the filter keyword followed by a unique identifier and define the filter conditions within curly braces.
Example:

filter MyCustomFilter {
    IP.Addr == "192.168.1.100" AND TCP.dstPort == 443
}

Q3: Can I use CIDR notation in filters?
A3: Yes, JNPL supports CIDR notation for efficient IP address range filtering.
Example:

filter SubnetFilter {
    IP.Addr in "10.0.0.0/24"
}

Q4: How do I apply multiple filters in an action?
A4: Use logical operators (AND, OR, NOT) within your filter definitions to combine multiple conditions. Then, reference the combined filter in your action.
Example:

filter CombinedFilter {
    Filter1 OR Filter2
}

action ApplyCombinedFilter {
    filter CombinedFilter
    // Additional action attributes
}

Q5: How can I delete an IpfMode configuration?
A5: Use the JNPL delete command followed by the IpfMode identifier or criteria. Refer to the Reference section for detailed commands.

Support

If you encounter any issues, have questions, or need assistance with JNPL, please reach out through the following channels:

GitHub Issues: Open an issue in the repository.
Community Forum: Join our JNPL Community Forum to discuss and seek help.
Email Support: Contact us at [email protected].

We strive to provide timely and helpful support to all JNPL users. Your feedback and contributions help improve the language and its documentation!

Happy Packet Filtering with JNPL! 🚀

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

1.2 JNPL Syntax

JNet Packet Language (JNPL) Wiki

Table of Contents

Introduction

Getting Started

Syntax Overview

Core Sections

Filters

IpfMode

Actions

Protocols

HashModes

Examples

Basic Example

Advanced Configuration

Best Practices

Reference

Grammar Specifications

IpfMode

Action

Filter

HashMode

Attribute Definitions

Contributing

FAQ

Support

Clone this wiki locally