field_engine.rst revision 9a3228de
1
2Field Engine modules 
3=======================
4
5The Field Engine (FE) has limited number of instructions/operation for supporting most use cases. 
6There is a plan to add LuaJIT to be more flexible at the cost of performance.
7The FE can allocate stream variables in a Stream context, write a stream variable to a packet offset, change packet size,  etc.
8
9*Some examples for what can be done:*
10
11* Change ipv4.tos 1-10
12* Change packet size to be random in the range 64-9K
13* Create range of flows (change src_ip, dest_ip, src_port, dest_port) 
14* Update IPv4 checksum 
15
16
17for example this snippet will create SYN Attack::
18
19    # create attack from random src_ip from 16.0.0.0-18.0.0.254 and random src_port 1025-65000    
20    # attack 48.0.0.1 server 
21        
22    def create_stream (self):
23
24        
25        # TCP SYN
26        base_pkt  = Ether()/IP(dst="48.0.0.1")/TCP(dport=80,flags="S")
27
28
29        # vm
30        vm = STLScVmRaw( [ STLVmFlowVar(name="ip_src", 
31                                              min_value="16.0.0.0", 
32                                              max_value="18.0.0.254", 
33                                              size=4, op="random"),
34
35                            STLVmFlowVar(name="src_port", 
36                                              min_value=1025, 
37                                              max_value=65000, 
38                                              size=2, op="random"),
39
40                           STLVmWrFlowVar(fv_name="ip_src", pkt_offset= "IP.src" ),
41
42                           STLVmFixIpv4(offset = "IP"), # fix checksum
43
44                           STLVmWrFlowVar(fv_name="src_port", 
45                                                pkt_offset= "TCP.sport") # fix udp len  
46
47                          ]
48                       )
49
50        pkt = STLPktBuilder(pkt = base_pkt,
51                            vm = vm)
52
53        return STLStream(packet = pkt,
54                         random_seed = 0x1234,# can be remove. will give the same random value any run
55                         mode = STLTXCont())
56
57
58
59
60STLScVmRaw class
61----------------
62
63Aggregate a raw instructions objects 
64
65.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLScVmRaw
66    :members: 
67    :member-order: bysource
68
69
70STLVmFlowVar 
71------------
72
73.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLVmFlowVar
74    :members: 
75    :member-order: bysource
76
77STLVmWrMaskFlowVar
78------------------
79
80.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLVmWrMaskFlowVar
81    :members: 
82    :member-order: bysource
83
84STLVmFixIpv4
85------------------
86
87.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLVmFixIpv4
88    :members: 
89    :member-order: bysource
90 
91
92STLVmTrimPktSize
93------------------
94
95.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLVmTrimPktSize
96    :members: 
97    :member-order: bysource
98
99STLVmTupleGen
100------------------
101
102.. autoclass:: trex_stl_lib.trex_stl_packet_builder_scapy.STLVmTupleGen
103    :members: 
104    :member-order: bysource
105
106  
107
108Field Engine snippet
109--------------------
110
111Example1:: 
112
113
114        base_pkt = Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
115
116        pad = max(0, size - len(base_pkt)) * 'x'
117                             
118        vm = STLScVmRaw( [   STLVmTupleGen ( ip_min="16.0.0.1", ip_max="16.0.0.2", 
119                                             port_min=1025, port_max=65535,
120                                             name="tuple"), # define tuple gen 
121
122                             # write ip to packet IP.src
123                             STLVmWrFlowVar (fv_name="tuple.ip", pkt_offset= "IP.src" ), 
124                             
125                             STLVmFixIpv4(offset = "IP"),  # fix checksum
126                             STLVmWrFlowVar (fv_name="tuple.port", pkt_offset= "UDP.sport" )  #write udp.port
127                                  ]
128                              );
129
130        pkt = STLPktBuilder(pkt = base_pkt/pad,
131                            vm = vm)
132
133        
134
135Example2::
136
137        #range of source mac-addr
138
139        base_pkt =  Ether()/IP(src="16.0.0.1",dst="48.0.0.1")/UDP(dport=12,sport=1025)
140        pad = max(0, size - len(base_pkt)) * 'x'
141
142        vm = STLScVmRaw( [ STLVmFlowVar(name="mac_src", 
143                                        min_value=1, 
144                                        max_value=30, 
145                                        size=2, op="dec",step=1), 
146                           STLVmWrMaskFlowVar(fv_name="mac_src", 
147                                              pkt_offset= 11, 
148                                              pkt_cast_size=1, 
149                                              mask=0xff) 
150                         ]
151                        )
152
153
154