Note: Our current website is at www.zeek.org. This website is unmaintained and contains outdated information.

Exercise: Extending a Script’s Functionality

TLS/SSL has been a hot topic lately and Bro’s TLS/SSL analysis scripts offer a strong base for extending and customizing analysis to suit one’s needs. The following exercises all demonstrate the types of things Bro’s base scripts can be extended to do.

Part 1: Customize Which Certificates to Trust

By default, Bro only knows how to trust the same CA root certificates as used by Mozilla. In these exercises, we’ll show how to add trust to custom certificates.

Exercise

First figure out how to get Bro to perform certificate validation on the TLS exchange found in the ssl-root-cert.pcap packet capture file, by loading a script found in the scripts/policy/protocols/ssl directory (or if you’re looking in the Bro installation directory, the scripts/ root is actually $prefix/share/bro). After running Bro loaded with that file on the pcap trace, how does Bro indicate through the log files that the server’s certificate is invalid?

Delete your logs at this point (rm *.log) so that we start fresh for the next exercise.

Exercise

Now get Bro to trust the server’s certificate, which can be found in a suitable format that Bro understands in cert-hexesc.der. You’ll have to redefine the same script variable that was originally used to define the Mozilla trust roots.

Exercise

As an optional task, try to figure out how to derive the hex-escaped version of the certificate in cert-hexesc.der from a typical DER encoded certificate in cert.der. This will require use of the openssl command-line client and maybe other command-line-fu (don’t spend too long if you get stuck).

Part 2: Log More Than Just Server Cert. Subject

Bro currently just logs the subject of SSL server certificates, but in this exercise, we’ll see how to extend what a script logs to also include the issuer of certificates.

Exercise

Write a script that extends the SSL logging to include the issuer of the server’s certificate offered in the exchange in the ssl-nonroot-cert.pcap trace file. You’ll need to redefine the SSL logging unit (SSL::Info) and handle x509_certificate event for this exercise. What are the subject and issuer of the server’s certificate?

Part 3: Using the Notice Framework

Most site policies will probably want to know a little about what SSL/TLS clients/servers are on their network such as the version and cipher suite they’re negotiating so that they can detect weak or old/outdated software. Bro can help.

Exercise

Write a script that adds a notice type for SSLv2 clients and then proceeds to generate a notice of that type whenever Bro sees a client offering the ability to negotiate that protocol. An example of such a transaction can be found in sslv2.pcap. By default, your generated notices should be observable in notice.log.