From dbf58be0e5f38dbbbd1733bb00dd62d1e930e8b0 Mon Sep 17 00:00:00 2001 From: Jon Siwek Date: Mon, 23 Mar 2015 13:04:53 -0500 Subject: [PATCH] Fix an example in quickstart docs. BIT-1226 #close --- CHANGES | 4 ++ VERSION | 2 +- doc/quickstart/conditional-notice.bro | 24 +++++++++ doc/quickstart/index.rst | 54 +++++++++---------- .../btest-doc.sphinx.conditional-notice#1 | 26 +++++++++ .../output | 28 ++++++++++ .../btest/doc/sphinx/conditional-notice.btest | 2 + ...oc_quickstart_conditional-notice_bro.btest | 28 ++++++++++ 8 files changed, 137 insertions(+), 31 deletions(-) create mode 100644 doc/quickstart/conditional-notice.bro create mode 100644 testing/btest/Baseline/doc.sphinx.conditional-notice/btest-doc.sphinx.conditional-notice#1 create mode 100644 testing/btest/Baseline/doc.sphinx.include-doc_quickstart_conditional-notice_bro/output create mode 100644 testing/btest/doc/sphinx/conditional-notice.btest create mode 100644 testing/btest/doc/sphinx/include-doc_quickstart_conditional-notice_bro.btest diff --git a/CHANGES b/CHANGES index 31ddf762eb..08a6fff2cf 100644 --- a/CHANGES +++ b/CHANGES @@ -1,4 +1,8 @@ +2.3-572 | 2015-03-23 13:04:53 -0500 + + * BIT-1226: Fix an example in quickstart docs. (Jon siwek) + 2.3-570 | 2015-03-23 09:51:20 -0500 * Correct a spelling error (Daniel Thayer) diff --git a/VERSION b/VERSION index c93efbe579..3ade82ed0d 100644 --- a/VERSION +++ b/VERSION @@ -1 +1 @@ -2.3-570 +2.3-572 diff --git a/doc/quickstart/conditional-notice.bro b/doc/quickstart/conditional-notice.bro new file mode 100644 index 0000000000..8cc01787c9 --- /dev/null +++ b/doc/quickstart/conditional-notice.bro @@ -0,0 +1,24 @@ +@load protocols/ssl/expiring-certs + +const watched_servers: set[addr] = { + 87.98.220.10, +} &redef; + +# Site::local_nets usually isn't something you need to modify if +# BroControl automatically sets it up from networks.cfg. It's +# shown here for completeness. +redef Site::local_nets += { + 87.98.0.0/16, +}; + +hook Notice::policy(n: Notice::Info) + { + if ( n$note != SSL::Certificate_Expired ) + return; + + if ( n$id$resp_h !in watched_servers ) + return; + + add n$actions[Notice::ACTION_EMAIL]; + } + diff --git a/doc/quickstart/index.rst b/doc/quickstart/index.rst index bb642ee75a..616c94c261 100644 --- a/doc/quickstart/index.rst +++ b/doc/quickstart/index.rst @@ -156,9 +156,11 @@ changes we want to make: notice that means an SSL connection was established and the server's certificate couldn't be validated using Bro's default trust roots, but we want to ignore it. -2) ``SSH::Login`` is a notice type that is triggered when an SSH connection - attempt looks like it may have been successful, and we want email when - that happens, but only for certain servers. +2) ``SSL::Certificate_Expired`` is a notice type that is triggered when + an SSL connection was established using an expired certificate. We + want email when that happens, but only for certain servers on the + local network (Bro can also proactively monitor for certs that will + soon expire, but this is just for demonstration purposes). We've defined *what* we want to do, but need to know *where* to do it. The answer is to use a script written in the Bro programming language, so @@ -203,7 +205,7 @@ the variable's value may not change at run-time, but whose initial value can be modified via the ``redef`` operator at parse-time. Let's continue on our path to modify the behavior for the two SSL -and SSH notices. Looking at :doc:`/scripts/base/frameworks/notice/main.bro`, +notices. Looking at :doc:`/scripts/base/frameworks/notice/main.bro`, we see that it advertises: .. code:: bro @@ -216,7 +218,7 @@ we see that it advertises: const ignored_types: set[Notice::Type] = {} &redef; } -That's exactly what we want to do for the SSL notice. Add to ``local.bro``: +That's exactly what we want to do for the first notice. Add to ``local.bro``: .. code:: bro @@ -248,38 +250,30 @@ is valid before installing it and then restarting the Bro instance: stopping bro ... starting bro ... -Now that the SSL notice is ignored, let's look at how to send an email on -the SSH notice. The notice framework has a similar option called -``emailed_types``, but using that would generate email for all SSH servers and -we only want email for logins to certain ones. There is a ``policy`` hook -that is actually what is used to implement the simple functionality of -``ignored_types`` and -``emailed_types``, but it's extensible such that the condition and action taken -on notices can be user-defined. +Now that the SSL notice is ignored, let's look at how to send an email +on the other notice. The notice framework has a similar option called +``emailed_types``, but using that would generate email for all SSL +servers with expired certificates and we only want email for connections +to certain ones. There is a ``policy`` hook that is actually what is +used to implement the simple functionality of ``ignored_types`` and +``emailed_types``, but it's extensible such that the condition and +action taken on notices can be user-defined. -In ``local.bro``, let's define a new ``policy`` hook handler body -that takes the email action for SSH logins only for a defined set of servers: +In ``local.bro``, let's define a new ``policy`` hook handler body: -.. code:: bro +.. btest-include:: ${DOC_ROOT}/quickstart/conditional-notice.bro - const watched_servers: set[addr] = { - 192.168.1.100, - 192.168.1.101, - 192.168.1.102, - } &redef; +.. btest:: conditional-notice - hook Notice::policy(n: Notice::Info) - { - if ( n$note == SSH::SUCCESSFUL_LOGIN && n$id$resp_h in watched_servers ) - add n$actions[Notice::ACTION_EMAIL]; - } + @TEST-EXEC: btest-rst-cmd bro -r ${TRACES}/tls/tls-expired-cert.trace ${DOC_ROOT}/quickstart/conditional-notice.bro + @TEST-EXEC: btest-rst-cmd cat notice.log You'll just have to trust the syntax for now, but what we've done is first declare our own variable to hold a set of watched addresses, -``watched_servers``; then added a hook handler body to the policy that will -generate an email whenever the notice type is an SSH login and the responding -host stored -inside the ``Info`` record's connection field is in the set of watched servers. +``watched_servers``; then added a hook handler body to the policy that +will generate an email whenever the notice type is an SSL expired +certificate and the responding host stored inside the ``Info`` record's +connection field is in the set of watched servers. .. note:: Record field member access is done with the '$' character instead of a '.' as might be expected from other languages, in diff --git a/testing/btest/Baseline/doc.sphinx.conditional-notice/btest-doc.sphinx.conditional-notice#1 b/testing/btest/Baseline/doc.sphinx.conditional-notice/btest-doc.sphinx.conditional-notice#1 new file mode 100644 index 0000000000..7217abc421 --- /dev/null +++ b/testing/btest/Baseline/doc.sphinx.conditional-notice/btest-doc.sphinx.conditional-notice#1 @@ -0,0 +1,26 @@ +.. rst-class:: btest-cmd + + .. code-block:: none + :linenos: + :emphasize-lines: 1,1 + + # bro -r tls/tls-expired-cert.trace conditional-notice.bro + +.. rst-class:: btest-cmd + + .. code-block:: none + :linenos: + :emphasize-lines: 1,1 + + # cat notice.log + #separator \x09 + #set_separator , + #empty_field (empty) + #unset_field - + #path notice + #open 2015-03-23-18-03-21 + #fields ts uid id.orig_h id.orig_p id.resp_h id.resp_p fuid file_mime_type file_desc proto note msg sub src dst p n peer_descr actions suppress_for dropped remote_location.country_code remote_location.region remote_location.city remote_location.latitude remote_location.longitude + #types time string addr port addr port string string string enum enum string string addr addr port count string set[enum] interval bool string string string double double + 1394745603.293028 CXWv6p3arKYeMETxOg 192.168.4.149 60539 87.98.220.10 443 F1fX1R2cDOzbvg17ye - - tcp SSL::Certificate_Expired Certificate CN=www.spidh.org,OU=COMODO SSL,OU=Domain Control Validated expired at 2014-03-04-23:59:59.000000000 - 192.168.4.149 87.98.220.10 443 - bro Notice::ACTION_EMAIL,Notice::ACTION_LOG 86400.000000 F - - - - - + #close 2015-03-23-18-03-21 + diff --git a/testing/btest/Baseline/doc.sphinx.include-doc_quickstart_conditional-notice_bro/output b/testing/btest/Baseline/doc.sphinx.include-doc_quickstart_conditional-notice_bro/output new file mode 100644 index 0000000000..8412154ec4 --- /dev/null +++ b/testing/btest/Baseline/doc.sphinx.include-doc_quickstart_conditional-notice_bro/output @@ -0,0 +1,28 @@ +# @TEST-EXEC: cat %INPUT >output && btest-diff output + +conditional-notice.bro + +@load protocols/ssl/expiring-certs + +const watched_servers: set[addr] = { + 87.98.220.10, +} &redef; + +# Site::local_nets usually isn't something you need to modify if +# BroControl automatically sets it up from networks.cfg. It's +# shown here for completeness. +redef Site::local_nets += { + 87.98.0.0/16, +}; + +hook Notice::policy(n: Notice::Info) + { + if ( n$note != SSL::Certificate_Expired ) + return; + + if ( n$id$resp_h !in watched_servers ) + return; + + add n$actions[Notice::ACTION_EMAIL]; + } + diff --git a/testing/btest/doc/sphinx/conditional-notice.btest b/testing/btest/doc/sphinx/conditional-notice.btest new file mode 100644 index 0000000000..ff3eea1132 --- /dev/null +++ b/testing/btest/doc/sphinx/conditional-notice.btest @@ -0,0 +1,2 @@ +@TEST-EXEC: btest-rst-cmd bro -r ${TRACES}/tls/tls-expired-cert.trace ${DOC_ROOT}/quickstart/conditional-notice.bro +@TEST-EXEC: btest-rst-cmd cat notice.log diff --git a/testing/btest/doc/sphinx/include-doc_quickstart_conditional-notice_bro.btest b/testing/btest/doc/sphinx/include-doc_quickstart_conditional-notice_bro.btest new file mode 100644 index 0000000000..8412154ec4 --- /dev/null +++ b/testing/btest/doc/sphinx/include-doc_quickstart_conditional-notice_bro.btest @@ -0,0 +1,28 @@ +# @TEST-EXEC: cat %INPUT >output && btest-diff output + +conditional-notice.bro + +@load protocols/ssl/expiring-certs + +const watched_servers: set[addr] = { + 87.98.220.10, +} &redef; + +# Site::local_nets usually isn't something you need to modify if +# BroControl automatically sets it up from networks.cfg. It's +# shown here for completeness. +redef Site::local_nets += { + 87.98.0.0/16, +}; + +hook Notice::policy(n: Notice::Info) + { + if ( n$note != SSL::Certificate_Expired ) + return; + + if ( n$id$resp_h !in watched_servers ) + return; + + add n$actions[Notice::ACTION_EMAIL]; + } +