Reorganize documentation index

Moved examples and use cases into a common subdir so those topics will
get grouped together in the main sidebar/TOC

doc/examples/scripting/connection_record_01.bro

@@ -0,0 +1,6 @@
+@load base/protocols/conn
+
+event connection_state_remove(c: connection)
+    {
+    print c;
+    }

doc/examples/scripting/connection_record_02.bro

@@ -0,0 +1,7 @@
+@load base/protocols/conn
+@load base/protocols/http
+
+event connection_state_remove(c: connection)
+    {
+    print c;
+    }

doc/examples/scripting/data_struct_record_01.bro

@@ -0,0 +1,22 @@
+type Service: record {
+    name: string;
+    ports: set[port];
+    rfc: count;
+};
+
+function print_service(serv: Service)
+    {
+    print fmt("Service: %s(RFC%d)",serv$name, serv$rfc);
+    
+    for ( p in serv$ports )
+        print fmt("  port: %s", p);
+    }
+
+event bro_init()
+    {
+    local dns: Service = [$name="dns", $ports=set(53/udp, 53/tcp), $rfc=1035];
+    local http: Service = [$name="http", $ports=set(80/tcp, 8080/tcp), $rfc=2616];
+    
+    print_service(dns);
+    print_service(http);
+    }

doc/examples/scripting/data_struct_record_02.bro

@@ -0,0 +1,41 @@
+type Service: record {
+    name: string;
+    ports: set[port];
+    rfc: count;
+    };
+
+type System: record {
+    name: string;
+    services: set[Service];
+    };
+
+function print_service(serv: Service)
+    {
+    print fmt("  Service: %s(RFC%d)",serv$name, serv$rfc);
+    
+    for ( p in serv$ports )
+        print fmt("    port: %s", p);
+    }
+
+function print_system(sys: System)
+    {
+    print fmt("System: %s", sys$name);
+    
+    for ( s in sys$services )
+        print_service(s);
+    }
+
+event bro_init()
+    {
+    local server01: System;
+    server01$name = "morlock";
+    add server01$services[[ $name="dns", $ports=set(53/udp, 53/tcp), $rfc=1035]];
+    add server01$services[[ $name="http", $ports=set(80/tcp, 8080/tcp), $rfc=2616]];
+    print_system(server01);
+    
+    
+    # local dns: Service = [ $name="dns", $ports=set(53/udp, 53/tcp), $rfc=1035];
+    # local http: Service = [ $name="http", $ports=set(80/tcp, 8080/tcp), $rfc=2616];
+    # print_service(dns);
+    # print_service(http);
+    }

doc/examples/scripting/data_struct_set_declaration.bro

@@ -0,0 +1,22 @@
+event bro_init()
+    {
+    local ssl_ports: set[port];
+    local non_ssl_ports = set( 23/tcp, 80/tcp, 143/tcp, 25/tcp );
+    
+    # SSH
+    add ssl_ports[22/tcp];
+    # HTTPS
+    add ssl_ports[443/tcp];
+    # IMAPS
+    add ssl_ports[993/tcp];
+    
+    # Check for SMTPS 
+    if ( 587/tcp !in ssl_ports )
+        add ssl_ports[587/tcp];
+    
+    for ( i in ssl_ports )
+        print fmt("SSL Port: %s", i);
+
+    for ( i in non_ssl_ports )
+        print fmt("Non-SSL Port: %s", i);
+    }

doc/examples/scripting/data_struct_table_complex.bro

@@ -0,0 +1,13 @@
+event bro_init()
+    {
+    local samurai_flicks: table[string, string, count, string] of string;
+    
+    samurai_flicks["Kihachi Okamoto", "Toho", 1968, "Tatsuya Nakadai"] = "Kiru";
+    samurai_flicks["Hideo Gosha", "Fuji", 1969, "Tatsuya Nakadai"] = "Goyokin";
+    samurai_flicks["Masaki Kobayashi", "Shochiku Eiga", 1962, "Tatsuya Nakadai" ] = "Harakiri";
+    samurai_flicks["Yoji Yamada", "Eisei Gekijo", 2002, "Hiroyuki Sanada" ] = "Tasogare Seibei";
+    
+    for ( [d, s, y, a] in samurai_flicks )
+        print fmt("%s was released in %d by %s studios, directed by %s and starring %s", samurai_flicks[d, s, y, a], y, s, d, a);
+    }
+

doc/examples/scripting/data_struct_table_declaration.bro

@@ -0,0 +1,19 @@
+event bro_init()
+    {
+    # Declaration of the table.
+    local ssl_services: table[string] of port;
+
+    # Initialize the table.
+    ssl_services = table(["SSH"] = 22/tcp, ["HTTPS"] = 443/tcp);
+
+    # Insert one key-yield pair into the table.
+    ssl_services["IMAPS"] = 993/tcp;
+
+    # Check if the key "SMTPS" is not in the table.
+    if ( "SMTPS" !in ssl_services )
+        ssl_services["SMTPS"] = 587/tcp;
+
+    # Iterate over each key in the table.
+    for ( k in ssl_services )
+        print fmt("Service Name:  %s - Common Port: %s", k, ssl_services[k]);
+    }

doc/examples/scripting/data_struct_vector.bro

@@ -0,0 +1,7 @@
+event bro_init()
+    {
+    local v: vector of count = vector(1, 2, 3, 4);
+    local w = vector(1, 2, 3, 4);
+    print v;
+    print w;
+    }

doc/examples/scripting/data_struct_vector_declaration.bro

@@ -0,0 +1,15 @@
+event bro_init()
+    {
+    local v1: vector of count;
+    local v2 = vector(1, 2, 3, 4);
+    
+    v1 += 1;
+    v1 += 2;
+    v1 += 3;
+    v1 += 4;
+    
+    print fmt("contents of v1: %s", v1);
+    print fmt("length of v1: %d", |v1|);
+    print fmt("contents of v2: %s", v2);
+    print fmt("length of v2: %d", |v2|);
+    }

doc/examples/scripting/data_struct_vector_iter.bro

@@ -0,0 +1,7 @@
+event bro_init()
+    {
+    local addr_vector: vector of addr = vector(1.2.3.4, 2.3.4.5, 3.4.5.6);
+
+    for (i in addr_vector)
+        print mask_addr(addr_vector[i], 18);
+    }

doc/examples/scripting/data_type_const.bro

@@ -0,0 +1,9 @@
+const port_list: table[port] of string &redef;
+
+redef port_list += { [6666/tcp] = "IRC"};
+redef port_list += { [80/tcp] = "WWW" };
+
+event bro_init()
+    {
+    print port_list;
+    }

doc/examples/scripting/data_type_const_simple.bro

@@ -0,0 +1,4 @@
+@load base/protocols/http
+
+redef HTTP::default_capture_password = T;
+

doc/examples/scripting/data_type_declaration.bro

@@ -0,0 +1,9 @@
+event bro_init()
+    {
+    local a: int;
+    a = 10;
+    local b = 10;
+
+    if ( a == b )
+        print fmt("A: %d, B: %d", a, b);
+    }

doc/examples/scripting/data_type_interval.bro

@@ -0,0 +1,18 @@
+# Store the time the previous connection was established.
+global last_connection_time: time;
+
+# boolean value to indicate whether we have seen a previous connection.
+global connection_seen: bool = F;
+
+event connection_established(c: connection)
+    {
+    local net_time: time  = network_time();
+
+    print fmt("%s:  New connection established from %s to %s", strftime("%Y/%M/%d %H:%m:%S", net_time), c$id$orig_h, c$id$resp_h);
+    
+    if ( connection_seen )
+        print fmt("     Time since last connection: %s", net_time - last_connection_time);
+    
+    last_connection_time = net_time;
+    connection_seen = T;
+    }

doc/examples/scripting/data_type_local.bro

@@ -0,0 +1,11 @@
+function add_two(i: count): count
+    {
+    local added_two = i+2;
+    print fmt("i + 2 = %d", added_two);
+    return added_two;
+    }
+
+event bro_init()
+    {
+    local test = add_two(10);
+    }

doc/examples/scripting/data_type_pattern_01.bro

@@ -0,0 +1,13 @@
+event bro_init()
+    {
+    local test_string = "The quick brown fox jumps over the lazy dog.";
+    local test_pattern = /quick|lazy/;
+    
+    if ( test_pattern in test_string )
+        {
+        local results = split(test_string, test_pattern);
+        print results[1];
+        print results[2];
+        print results[3];
+        }
+    }

doc/examples/scripting/data_type_pattern_02.bro

@@ -0,0 +1,10 @@
+event bro_init()
+    {
+    local test_string = "equality";
+
+    local test_pattern = /equal/;
+    print fmt("%s and %s %s equal", test_string, test_pattern, test_pattern == test_string ? "are" : "are not");
+    
+    test_pattern = /equality/;
+    print fmt("%s and %s %s equal", test_string, test_pattern, test_pattern == test_string ? "are" : "are not");
+    }

doc/examples/scripting/data_type_record.bro

@@ -0,0 +1,25 @@
+module Conn;
+
+export {
+	## The record type which contains column fields of the connection log.
+	type Info: record {
+		ts:           time            &log;
+		uid:          string          &log;
+		id:           conn_id         &log;
+		proto:        transport_proto &log;
+		service:      string          &log &optional;
+		duration:     interval        &log &optional;
+		orig_bytes:   count           &log &optional;
+		resp_bytes:   count           &log &optional;
+		conn_state:   string          &log &optional;
+		local_orig:   bool            &log &optional;
+		local_resp:   bool            &log &optional;
+		missed_bytes: count           &log &default=0;
+		history:      string          &log &optional;
+		orig_pkts:     count      &log &optional;
+		orig_ip_bytes: count      &log &optional;
+		resp_pkts:     count      &log &optional;
+		resp_ip_bytes: count      &log &optional;
+		tunnel_parents: set[string] &log;
+	};
+}

doc/examples/scripting/data_type_subnets.bro

@@ -0,0 +1,15 @@
+event bro_init()
+    {
+    local subnets = vector(172.16.0.0/20, 172.16.16.0/20, 172.16.32.0/20, 172.16.48.0/20);
+    local addresses = vector(172.16.4.56, 172.16.47.254, 172.16.22.45, 172.16.1.1);
+    
+    for ( a in addresses )
+        {
+        for ( s in subnets )
+            {
+            if ( addresses[a] in subnets[s] )
+                print fmt("%s belongs to subnet %s", addresses[a], subnets[s]);
+            }
+        }
+
+    }

doc/examples/scripting/data_type_time.bro

@@ -0,0 +1,4 @@
+event connection_established(c: connection)
+    {
+    print fmt("%s:  New connection established from %s to %s\n", strftime("%Y/%M/%d %H:%m:%S", network_time()), c$id$orig_h, c$id$resp_h);
+    }

doc/examples/scripting/framework_logging_factorial_01.bro

@@ -0,0 +1,19 @@
+module Factor;
+
+function factorial(n: count): count
+    {
+    if ( n == 0 )
+        return 1;
+    else
+        return ( n * factorial(n - 1) );
+    }
+
+event bro_init()
+    {
+    local numbers: vector of count = vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);
+    
+    for ( n in numbers )
+        print fmt("%d", factorial(numbers[n]));
+    }
+
+

doc/examples/scripting/framework_logging_factorial_02.bro

@@ -0,0 +1,35 @@
+module Factor;
+
+export {
+    # Append the value LOG to the Log::ID enumerable.
+    redef enum Log::ID += { LOG };
+
+    # Define a new type called Factor::Info.
+    type Info: record {
+        num:           count &log;
+        factorial_num: count &log;
+        };
+    }
+
+function factorial(n: count): count
+    {
+    if ( n == 0 )
+        return 1;
+    
+    else
+        return ( n * factorial(n - 1) );
+    }
+
+event bro_init()
+    {
+    # Create the logging stream.
+    Log::create_stream(LOG, [$columns=Info, $path="factor"]);
+    }
+
+event bro_done()
+    {
+    local numbers: vector of count = vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);    
+    for ( n in numbers )
+        Log::write( Factor::LOG, [$num=numbers[n],
+                                  $factorial_num=factorial(numbers[n])]);
+    }

doc/examples/scripting/framework_logging_factorial_03.bro

@@ -0,0 +1,45 @@
+module Factor;
+
+export {
+    redef enum Log::ID += { LOG };
+
+    type Info: record {
+        num:           count &log;
+        factorial_num: count &log;
+        };
+    }
+
+function factorial(n: count): count
+    {
+    if ( n == 0 )
+        return 1;
+    
+    else
+        return (n * factorial(n - 1));
+    }
+
+event bro_done()
+    {
+    local numbers: vector of count = vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);    
+    for ( n in numbers )
+        Log::write( Factor::LOG, [$num=numbers[n],
+                                  $factorial_num=factorial(numbers[n])]);
+    }
+
+function mod5(id: Log::ID, path: string, rec: Factor::Info) : string    
+    {
+    if ( rec$factorial_num % 5 == 0 )
+        return "factor-mod5";
+    
+    else
+        return "factor-non5";
+    }
+
+event bro_init()
+    {
+    Log::create_stream(LOG, [$columns=Info, $path="factor"]);
+    
+    local filter: Log::Filter = [$name="split-mod5s", $path_func=mod5];
+    Log::add_filter(Factor::LOG, filter);
+    Log::remove_filter(Factor::LOG, "default");
+    }

doc/examples/scripting/framework_logging_factorial_04.bro

@@ -0,0 +1,50 @@
+module Factor;
+
+export {
+    redef enum Log::ID += { LOG };
+
+    type Info: record {
+        num:           count &log;
+        factorial_num: count &log;
+        };
+    
+    global log_factor: event(rec: Info);
+    }
+
+function factorial(n: count): count
+    {
+    if ( n == 0 )
+        return 1;
+    
+    else
+        return (n * factorial(n - 1));
+    }
+
+event bro_init()
+    {
+    Log::create_stream(LOG, [$columns=Info, $ev=log_factor, $path="factor"]);
+    }
+
+event bro_done()
+    {
+    local numbers: vector of count = vector(1, 2, 3, 4, 5, 6, 7, 8, 9, 10);    
+    for ( n in numbers )
+        Log::write( Factor::LOG, [$num=numbers[n],
+                                  $factorial_num=factorial(numbers[n])]);
+    }
+
+function mod5(id: Log::ID, path: string, rec: Factor::Info) : string    
+    {
+    if ( rec$factorial_num % 5 == 0 )
+        return "factor-mod5";
+    
+    else
+        return "factor-non5";
+    }
+
+event bro_init()
+    {
+    local filter: Log::Filter = [$name="split-mod5s", $path_func=mod5];
+    Log::add_filter(Factor::LOG, filter);
+    Log::remove_filter(Factor::LOG, "default");
+    }

doc/examples/scripting/framework_notice_hook_01.bro

@@ -0,0 +1,7 @@
+@load policy/protocols/ssh/interesting-hostnames.bro
+
+hook Notice::policy(n: Notice::Info)
+  {
+  if ( n$note == SSH::Interesting_Hostname_Login )
+      add n$actions[Notice::ACTION_EMAIL];
+  }

doc/examples/scripting/framework_notice_hook_suppression_01.bro

@@ -0,0 +1,7 @@
+@load policy/protocols/ssl/expiring-certs.bro
+
+hook Notice::policy(n: Notice::Info) 
+   {
+   if ( n$note == SSL::Certificate_Expires_Soon )
+       n$suppress_for = 12hrs;
+   }

doc/examples/scripting/framework_notice_shortcuts_01.bro

@@ -0,0 +1,7 @@
+@load policy/protocols/ssh/interesting-hostnames.bro
+@load base/protocols/ssh/
+
+redef Notice::emailed_types += {
+    SSH::Interesting_Hostname_Login
+};
+

doc/examples/scripting/framework_notice_shortcuts_02.bro

@@ -0,0 +1,6 @@
+@load policy/protocols/ssh/interesting-hostnames.bro
+@load base/protocols/ssh/
+
+redef Notice::type_suppression_intervals += {
+    [SSH::Interesting_Hostname_Login] = 1day,
+};

doc/examples/scripting/http_main.bro

@@ -0,0 +1,7 @@
+module HTTP;
+
+export {
+	## This setting changes if passwords used in Basic-Auth are captured or
+	## not.
+	const default_capture_password = F &redef;
+}

doc/examples/scripting/using_bro_sandbox_01

@@ -0,0 +1,4 @@
+# @TEST-EXEC: bro -r ${TRACES}/wikipedia.trace
+# @TEST-EXEC: btest-diff conn.log
+# @TEST-EXEC: btest-diff http.log
+

doc/examples/scripting/using_bro_sandbox_02

@@ -0,0 +1,4 @@
+# @TEST-EXEC: bro -r ${TRACES}/workshop_2011_browse.trace
+# @TEST-EXEC: btest-diff conn.log
+# @TEST-EXEC: btest-diff http.log
+