├── .gitignore ├── COPYING ├── README.markdown ├── bro-cheat-sheet.pdf ├── bro-cheat-sheet.tex ├── cprotect.sty └── figs ├── bro-logo-small.pdf ├── by-nc-sa.pdf ├── shot-bif.png └── shot-main.png /.gitignore: -------------------------------------------------------------------------------- 1 | *.aux 2 | *.cpt 3 | *.fdb_latexmk 4 | *.fls 5 | *.log 6 | *.out 7 | *.sw[op] 8 | -------------------------------------------------------------------------------- /COPYING: -------------------------------------------------------------------------------- 1 | This work is licensed under the following license: 2 | 3 | Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported 4 | 5 | To view a full copy of this license, visit 6 | 7 | http://creativecommons.org/licenses/by-nc-sa/3.0/ 8 | 9 | or send a letter to: 10 | 11 | Creative Commons 12 | 444 Castro Street, Suite 900 13 | Mountain View, California, 94041 14 | USA 15 | 16 | The excerpt below is a human-readable summary of the Legal Code taken from the 17 | website above. 18 | 19 | =============================================================================== 20 | 21 | You are free: 22 | 23 | * to Share - to copy, distribute and transmit the work 24 | 25 | * to Remix - to adapt the work 26 | 27 | Under the following conditions: 28 | 29 | * Attribution - You must attribute the work in the manner specified by the 30 | author or licensor (but not in any way that suggests that they endorse 31 | you or your use of the work). 32 | 33 | * Noncommercial - You may not use this work for commercial purposes. 34 | 35 | * Share Alike - If you alter, transform, or build upon this work, you may 36 | distribute the resulting work only under the same or similar license to 37 | this one. 38 | 39 | With the understanding that: 40 | 41 | * Waiver - Any of the above conditions can be waived if you get permission 42 | from the copyright holder. 43 | 44 | * Public Domain - Where the work or any of its elements is in the public 45 | domain under applicable law, that status is in no way affected by the 46 | license. 47 | 48 | * Other Rights - In no way are any of the following rights affected by the 49 | license: 50 | 51 | - Your fair dealing or fair use rights, or other applicable copyright 52 | exceptions and limitations; 53 | 54 | - The author's moral rights; 55 | 56 | - Rights other persons may have either in the work itself or in how the 57 | work is used, such as publicity or privacy rights. 58 | 59 | * Notice - For any reuse or distribution, you must make clear to others the 60 | license terms of this work. The best way to do this is with a link to 61 | this web page. 62 | -------------------------------------------------------------------------------- /README.markdown: -------------------------------------------------------------------------------- 1 | Bro Cheat Sheet 2 | =============== 3 | 4 | This repository features the official Bro language cheat sheet, which 5 | succinctly summarizes the key components of the Bro scripting language and 6 | describes the built-in functions (BiFs). 7 | 8 | Tweaking 9 | -------- 10 | It turns out that Bro provides more features than we could fit on single 11 | double-sided sheet. Particularly the documentation of all BiFs consumes a lot 12 | of space, although we only selected a subset of functions that we deem relevant 13 | for the majority of users. Still, there exist folks who may want a complete 14 | "desktop reference" rather than a succinct cheat sheet. If you prefer to have 15 | *all* BiFs included on the cheat sheet, download the LaTeX source and uncomment 16 | the line 17 | 18 | %\verbosetrue 19 | 20 | at the beginning of the file. Then use your favorite LaTeX compiler (e.g., 21 | `pdflatex`) to build the verbose version of the cheat sheet with additional, 22 | more low-level BiFs. However, we emphasize that you will *not* need these extra 23 | BiFs in 99% of your scripting experience, because they are either extremely 24 | rarely used or already wrapped behind more accessible interfaces in the base 25 | scripts. 26 | 27 | License 28 | ------- 29 | 30 | This work is licensed under the 31 | **Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported** 32 | license. Please see the file COPYING for more information. 33 | 34 | Screenshots 35 | ----------- 36 | 37 | Below are two screenshots of the cheat sheet. 38 | 39 | ![Page 1](https://github.com/bro/cheat-sheet/raw/master/figs/shot-main.png) 40 | 41 | ![Page 2](https://github.com/bro/cheat-sheet/raw/master/figs/shot-bif.png) 42 | -------------------------------------------------------------------------------- /bro-cheat-sheet.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeek/cheat-sheet/9ab06d802b1f321a4862ce417d012d5701ba7ba1/bro-cheat-sheet.pdf -------------------------------------------------------------------------------- /bro-cheat-sheet.tex: -------------------------------------------------------------------------------- 1 | % This work is licensed under the 2 | % 3 | % Creative Commons Attribution-NonCommercial-ShareAlike 3.0 Unported 4 | % 5 | % license. Please see the file COPYING for more information. 6 | \documentclass[10pt,landscape]{article} 7 | 8 | \usepackage{alltt} 9 | \usepackage{cprotect} 10 | \usepackage{enumitem} 11 | \usepackage[T1]{fontenc} 12 | \usepackage[landscape,margin=13mm,footskip=1pt,includefoot]{geometry} 13 | \usepackage{graphicx} 14 | \usepackage{hyperref} 15 | \usepackage[utf8]{inputenc} 16 | \usepackage{multicol} 17 | \usepackage{setspace} 18 | %\usepackage[compact]{titlesec} 19 | \usepackage{upquote} 20 | \usepackage{xspace} 21 | 22 | \newif\ifverbose 23 | 24 | % The verbose flag controls the amount of content included. If \verbosetrue is 25 | % defined, the cheat sheet will include numerous additional built-in functions 26 | % that we deem too low-level for the majority of users. However, we still 27 | % include their documentation in the source code for the sake of completeness, 28 | % but you have to explicitly enable it by setting \verbosetrue (or simply 29 | % uncommenting the line below). 30 | % 31 | %\verbosetrue 32 | 33 | \graphicspath{{figs/}} 34 | 35 | \pagestyle{empty} 36 | \parindent=0pt 37 | 38 | \setitemize{itemsep=1pt,topsep=0pt,parsep=1pt,leftmargin=10pt} 39 | 40 | \hypersetup{ 41 | colorlinks=true, % false: boxed links; true: colored links 42 | linkcolor=red, % color of internal links 43 | citecolor=cyan, % color of links to bibliography 44 | filecolor=magenta, % color of file links 45 | urlcolor=blue % color of external links 46 | } 47 | 48 | \ifverbose 49 | \newcommand{\verbose}[1]{#1} 50 | \else 51 | \newcommand{\verbose}[1]{} 52 | \fi 53 | \cMakeRobust{\verbose} 54 | 55 | \newcommand{\todo}[1]{\textit{\textcolor{red}{TODO: #1}}} 56 | \newcommand{\minisec}[1]{\textsc{#1}\\} 57 | \newcommand{\first}{\emph{(i)}~} 58 | \newcommand{\second}{\emph{(ii)}~} 59 | \newcommand{\third}{\emph{(iii)}~} 60 | \newcommand{\fourth}{\emph{(iv)}~} 61 | \newcommand{\fifth}{\emph{(v)}~} 62 | 63 | % Generic phrase when functions return a boolean flag that indicates whether 64 | % the operation succeeded. 65 | \newcommand{\ReturnsTrueOnSuccess}{Returns true on success.\xspace} 66 | 67 | \begin{document} 68 | 69 | \begin{multicols*}{3} 70 | 71 | {\Huge\scshape 72 | Bro\hspace{-2pt}\raisebox{15pt}{\tiny2.2}\hspace{-4pt} 73 | Cheat Sheet} 74 | 75 | \hfill\includegraphics[width=.4\linewidth]{bro-logo-small} 76 | \vspace{-38pt} 77 | 78 | {\scriptsize 79 | \setstretch{1.5} 80 | \begin{tabular}{l l} 81 | Version: & \today\\ 82 | Website: & \url{http://www.bro-ids.org}\\ 83 | Email: & \texttt{\href{mailto:info@bro-ids.org}{info@bro-ids.org}}\\ 84 | Download: & \url{https://github.com/bro/cheat-sheet}\\ 85 | License: & \href{http://creativecommons.org/licenses/by-nc-sa/3.0/} 86 | {Attribution-NonCommercial-ShareAlike 3.0 Unported} 87 | \end{tabular} 88 | } 89 | 90 | %\hfill 91 | %\href{http://creativecommons.org/licenses/by-nc-sa/3.0/} 92 | %{\includegraphics[width=.2\linewidth]{by-nc-sa}} 93 | %\vspace{-10pt} 94 | 95 | \vspace{-10pt} 96 | 97 | \section*{Startup} 98 | 99 | \texttt{bro \textit{[options] [file \dots]}}\\ 100 | \texttt{\textit{file}} \dotfill Bro policy script or \texttt{stdin}\\ 101 | \texttt{-e \textit{code}} \dotfill Augment policies by given code\\ 102 | \texttt{-h} \dotfill Display command line options\\ 103 | \texttt{-i \textit{iface}} \dotfill Read from given interface\\ 104 | \texttt{-p \textit{pfx}} \dotfill Add given prefix to policy resolution\\ 105 | \texttt{-r \textit{file}} \dotfill Read from given PCAP file\\ 106 | \texttt{-w \textit{file}} \dotfill Write to given file in PCAP format\\ 107 | \texttt{-x \textit{file}} \dotfill Print contents of state file\\ 108 | \texttt{-C} \dotfill Ignore invalid checksum 109 | 110 | \section*{Language} 111 | 112 | Lowercase letters represent instance variables and uppercase letters represent 113 | types. In general, \texttt{x} is an instance of type \texttt{\textit{T}} and 114 | \texttt{y} an instance of type \texttt{\textit{U}}. Argument names and record 115 | fields begin with \texttt{a}, \texttt{b},~\ldots, and \texttt{z} represents a 116 | default instance variable which takes on the type of the right-hand side 117 | expression. For notational convenience, \texttt{x} can often be replaced with 118 | an expression of type \texttt{\textit{T}}. 119 | 120 | \subsection*{Variables} 121 | 122 | Constant qualifier \dotfill \texttt{const}\\ 123 | Constant redefinition \dotfill \texttt{redef x \textit{op} \textit{expr}}\\ 124 | Scope qualifier \dotfill \texttt{local}, \texttt{global}\\ 125 | Declaration \dotfill \texttt{\textit{scope} x:~\textit{T}}\\ 126 | Declaration \& Definition \dotfill \texttt{\textit{scope} z = \textit{expr}} 127 | 128 | \subsection*{Declarations} 129 | 130 | Type \dotfill \texttt{type~\textit{name}:~\textit{T}}\\ 131 | Function \dotfill \texttt{function~f(a:~\textit{T},~...):~\textit{R}}\\ 132 | Event \dotfill \texttt{event~e(a:~\textit{T},~...)} 133 | 134 | \subsection*{Modules} 135 | 136 | Script import \dotfill \texttt{@load \textit{path}}\\ 137 | Set current namespace to \texttt{ns} \dotfill \texttt{module \textit{ns}}\\ 138 | Export global symbols \dotfill \verb|export { ... }|\\ 139 | Access \texttt{module} or \texttt{enum} namespace \dotfill \verb|T::a| 140 | 141 | \subsection*{Statements} 142 | 143 | Basic statement \dotfill 144 | \texttt{\textit{stmt};} or \texttt{\textit{expr};}\\ 145 | Code block \dotfill \texttt{\{ \textit{stmt}; ... \}}\\ 146 | Assignment \dotfill \texttt{z = \textit{expr}}\\ 147 | Function assignment \dotfill \texttt{z~=~function(...):~\textit{R}~\{..\}}\\ 148 | Event queuing \dotfill \verb|event e(...)|\\ 149 | Event scheduling \dotfill \verb|schedule 10 secs { e(...) }|\\ 150 | Print expression to \texttt{stdout} \dotfill \texttt{print \textit{expr}}\\ 151 | 152 | \vspace{-10pt} 153 | %\minisec{Control Flow} 154 | \begin{multicols*}{3} 155 | \textsc{Branching} 156 | \begin{alltt} 157 | if (\textit{expr}) 158 | \{ \ldots \} 159 | else if (\textit{expr}) 160 | \{ \ldots \} 161 | else 162 | \{ \ldots \} 163 | \end{alltt} 164 | 165 | \textsc{Iteration} 166 | \begin{alltt} 167 | for (i in x) 168 | \{ \ldots \} 169 | \end{alltt} 170 | 171 | \textsc{Asynchronous} 172 | \begin{alltt} 173 | when (\textit{expr}) \{ \ldots \} 174 | when (local x = \textit{expr}) \{ \ldots \} 175 | \end{alltt} 176 | \vspace{-10pt} 177 | 178 | \begin{alltt} 179 | \textsc{Control}\vspace{5pt} 180 | break 181 | continue 182 | next 183 | return 184 | \end{alltt} 185 | \end{multicols*} 186 | 187 | \subsection*{Expressions} 188 | 189 | \minisec{Operators} 190 | \verb|!| \dotfill Negation\\ 191 | \verb|$|, \verb|?$| \dotfill Dereference, record field existence\\ 192 | \verb|+|, \verb|-|, \verb|*|, \verb|/|, \verb|%| \dotfill Arithmetic\\ 193 | \verb|++|, \verb|--| \dotfill Post-increment, post-decrement\\ 194 | \verb|+=|, \verb|-=|, \verb|*=|, \verb|/=| \dotfill Arithmetic and assignment\\ 195 | \verb|==|, \verb|!=| \dotfill Equality, inequality\\ 196 | \verb|<|, \verb|<=|, \verb|>=|, \verb|>| 197 | \dotfill Less/greater than (or equal)\\ 198 | \verb|&&|, \verb#||# \dotfill Conjunction, disjunction\\ 199 | \verb|in|, \verb|!in| \dotfill Membership or pattern matching\\ 200 | \verb|[x]| \dotfill Index strings and containers\\ 201 | \verb#|x|# \dotfill Cardinality/size for addresses, strings, containers\\ 202 | \verb|f(...)| \dotfill Function call\\ 203 | \texttt{\textit{expr}$\;$?$\;$\textit{expr}$\;$:$\;$\textit{expr}} 204 | \dotfill Ternary if-then-else 205 | 206 | \subsection*{Types} 207 | 208 | \minisec{Basic} 209 | \verb|addr| \dotfill IP address (v4: \verb|127.0.0.1|, v6: \verb|[fe80::db15]|)\\ 210 | \verb|bool| \dotfill Boolean flag (\verb|T|, \verb|F|)\\ 211 | \verb|count| \dotfill 64-bit unsigned integer (\verb|42|)\\ 212 | \verb|double| \dotfill Double-precision floating point (\verb|99.9|)\\ 213 | \verb|int| \dotfill 64-bit signed integer (\verb|-7|)\\ 214 | \verb|interval| \dotfill Time interval 215 | (\verb|8 sec|/\verb|min|/\verb|hr|/\verb|day[s]|)\\ 216 | \verb|pattern| \dotfill Regular expression (\verb|/^br[oO])$/|)\\ 217 | \verb|port| \dotfill Transport-layer port 218 | (\verb|22/tcp|, \verb|53/udp|)\\ 219 | \verb|string| \dotfill String of bytes (\verb|"foo"|)\\ 220 | \verb|subnet| \dotfill CIDR subnet mask (\verb|10.0.0.0/8|)\\ 221 | \verb|time| \dotfill Absolute epoch time (\verb|1320977325|)\\ 222 | 223 | \minisec{Enumerables} 224 | Declaration \dotfill \verb|enum { FOO, BAR }|\\ 225 | Assignment \dotfill \texttt{\textit{scope}} \verb|x = FOO|\\ 226 | 227 | \minisec{Records} 228 | Declaration \dotfill \texttt{record~\{~a:~\textit{T},~b:~\textit{U},~... \}}\\ 229 | Constructor \dotfill \verb|record($a=x, $b=y, ...)|\\ 230 | Assignment \dotfill \texttt{\textit{scope}} \verb|r = [$a=x, $b=y, ...]|\\ 231 | Access \dotfill \verb|z = r$a|\\ 232 | Field assignment \dotfill \verb|r$b = y|\\ 233 | Deletion \dotfill \verb|delete r$a|\\ 234 | 235 | \minisec{Sets} 236 | Declaration \dotfill \texttt{set[\textit{T}]}\\ 237 | Constructor \dotfill \verb|set(x, ...)|\\ 238 | Assignment \dotfill \texttt{\textit{scope}} \verb|s = { x, ... }|\\ 239 | Access \dotfill \verb|z = s[x]|\\ 240 | Insertion \dotfill \verb|add s[x]|\\ 241 | Deletion \dotfill \verb|delete s[x]|\\ 242 | 243 | \minisec{Tables} 244 | Declaration \dotfill \texttt{table[\textit{T}]~of~\textit{U}}\\ 245 | Constructor \dotfill \verb|table([x] = y, ...)|\\ 246 | Assignment \dotfill \texttt{\textit{scope}} \verb|t = { [x] = y, ... }|\\ 247 | Access \dotfill \verb|z = t[x]|\\ 248 | Insertion \dotfill \verb|t[x] = y|\\ 249 | Deletion \dotfill \verb|delete t[x]|\\ 250 | 251 | \minisec{Vectors} 252 | Declaration \dotfill \texttt{vector~of~\textit{T}}\\ 253 | Constructor \dotfill \verb|vector(x, ...)|\\ 254 | Assignment \dotfill \texttt{\textit{scope}} \verb|v = { x, ... }|\\ 255 | Access \dotfill \verb|z = v[0]|\\ 256 | Insertion \dotfill \verb|v[42] = x| 257 | % TODO. Not yet supported in Bro, see #679. 258 | %Deletion \dotfill \verb|delete v[3]| 259 | \end{multicols*} 260 | 261 | \begin{multicols*}{2} 262 | \subsection*{Attributes} 263 | Attributes occur at the end of type/event declarations and change their 264 | behavior. The syntax is \verb|&key| or \verb|&key=val|, e.g., 265 | \verb|type T: set[count] &read_expire=5min| or 266 | \verb|event foo() &priority=-3|.\\ 267 | 268 | \verb|&optional| \dotfill Allow record field to be missing\\ 269 | \verb|&default=x| \dotfill Use default value \texttt{x} for record fields and 270 | container elements\\ 271 | \verb|&redef| \dotfill Allow for redefinition of initial object value\\ 272 | % Users should use the logging framework instead. 273 | %\verb|&rotate_interval=x| \dotfill Rotate file after time \verb|x|\\ 274 | %\verb|&rotate_size=x| \dotfill Rotate file after reaching size limit \verb|x|\\ 275 | % 276 | % These do not seem to be worthwhile including 277 | %\verb|&add_func=f| \dotfill Call \verb|f| after adding element to container\\ 278 | %\verb|&delete_func=f| \dotfill Call \verb|f| before deleting element from 279 | %container \\ 280 | \verb|&expire_func=f| \dotfill Call \verb|f| right before container element 281 | expires\\ 282 | \verb|&read_expire=x| \dotfill Remove element after not reading it for time 283 | \verb|x|\\ 284 | \verb|&write_expire=x| \dotfill Remove element after not writing it for time 285 | \verb|x|\\ 286 | \verb|&create_expire=x| \dotfill Remove element after time \verb|x| from 287 | insertion\\ 288 | \verb|&persistent| \dotfill Write state to disk (per default on shutdown)\\ 289 | \verb|&synchronized| \dotfill Synchronize variable across nodes\\ 290 | \verb|&raw_output| \dotfill Do not escape non-ASCII characters when writing to 291 | a file\\ 292 | \verb|&mergeable| \dotfill Prefer set union to assignment for synchronized 293 | state\\ 294 | \verb|&priority=x| \dotfill Execution priority of event handler, higher values 295 | first, default 0\\ 296 | %$\mathtt{x} \in [-10,10]$ by convention\\ 297 | \verb|&group="x"| \dotfill Events in the same group can be jointly 298 | activated/deactivated\\ 299 | \verb|&log| \dotfill Write record field to log \\ 300 | 301 | \subsection*{Built-In Functions (BIFs)} 302 | \linespread{0.9} 303 | 304 | \subsubsection*{Core} 305 | 306 | \begin{itemize} 307 | \verbose{ 308 | \item \verb|getenv(var: string): string|\\ 309 | Returns the system environment variable identified by \verb|var|, or an 310 | empty string if it is not defined. 311 | \item \verb|setenv(var: string, val: string): bool|\\ 312 | Sets the system environment variable \verb|var| to \verb|val|. 313 | \ReturnsTrueOnSuccess 314 | } 315 | \item \verb|syslog(s: string)|\\ 316 | Send the string \verb|s| to syslog. 317 | \item \verb|system(s: string): int|\\ 318 | Invokes a command via the \texttt{system} function. 319 | Returns the return value from the \texttt{system()} call. 320 | \verbose{ 321 | Note that this corresponds to the status of backgrounding the given 322 | command, not to the exit status of the command itself. A value of 127 323 | corresponds to a failure to execute \verb|sh|, and -1 to an internal system 324 | failure. 325 | } 326 | The command is run in the background, \verb|stdout| redirects to 327 | \verb|stderr|. Here is a usage example: 328 | \verb|system(fmt("rm \"%s\"", str_shell_escape(sniffed_data)));| 329 | \verbose{ 330 | \item \verb|system_env(s: string, env: table[string] of string): int|\\ 331 | Same as \verb|system|, but prepare the environment before invoking the 332 | command \verb|s| with the set/table \verb|env|. 333 | } 334 | \item \verb|piped_exec(program: string, to_write: string): bool|\\ 335 | Opens the application \verb|program| with \verb|popen| and writes the 336 | string \verb|to_write| to \texttt{stdin} of the opened program. 337 | \item \verb|srand(seed: count)|\\ 338 | Sets the seed for subsequent \verb|rand| calls. 339 | \item \verb|rand(max: count): count|\\ 340 | Returns a random value from the interval $[0, \mathtt{max})$. 341 | \item \verb|md5_hash(...): string|\\ 342 | Computes the MD5 hash value of the provided list of arguments. 343 | \item \verb|md5_hash_init(): opaque of md5|\\ 344 | Retrieves an opaque handle for incremental MD5 hash computation. Add data 345 | with via \verb|md5_hash_update|. 346 | \item \verb|md5_hash_update(handle: opaque of md5, data: string): bool|\\ 347 | Feeds an incremental MD5 computation with \verb|data|. Call 348 | \verb|md5_hash_finish(handle)| to retrieve the final hash digest. 349 | \item \verb|md5_hash_finish(handle: opaque of md5): string|\\ 350 | Returns the final MD5 digest of \verb|handle|. This invalidates 351 | \verb|handle|, i.e., the function can only be called once. 352 | \item \verb|md5_hmac(...): string|\\ 353 | Computes an HMAC-MD5 hash value of the provided list of arguments. The HMAC 354 | secret key is generated from available entropy when Bro starts up, or it 355 | can be specified for repeatability using the \texttt{-K} flag. 356 | \item \verb|sha1_hash(...): string|\\ 357 | Computes the SHA1 hash value of the provided list of arguments. 358 | Analogous to \verb|md5_hash|. 359 | \item \verb|sha1_hash(...): string|\\ 360 | Computes the SHA1 hash value of the provided list of arguments. 361 | \item \verb|sha1_hash_init(): opaque of sha1|\\ 362 | Retrieves an opaque handle for incremental SHA1 hash computation. Add data 363 | with via \verb|sha1_hash_update|. 364 | \item \verb|sha1_hash_update(handle: opaque of sha1, data: string): bool|\\ 365 | Feeds an incremental SHA1 computation with \verb|data|. Call 366 | \verb|sha1_hash_finish(handle)| to retrieve the final hash digest. 367 | \item \verb|sha1_hash_finish(handle: opaque of sha1): string|\\ 368 | Returns the final SHA1 digest of \verb|handle|. This invalidates 369 | \verb|handle|, i.e., the function can only be called once. 370 | \item \verb|sha256_hash(...): string|\\ 371 | Computes the SHA256 hash value of the provided list of arguments. 372 | Analogous to \verb|md5_hash|. 373 | \item \verb|sha256_hash(...): string|\\ 374 | Computes the SHA256 hash value of the provided list of arguments. 375 | \item \verb|sha256_hash_init(): opaque of sha256|\\ 376 | Retrieves an opaque handle for incremental SHA256 hash computation. Add data 377 | with via \verb|sha256_hash_update|. 378 | \item \verb|sha256_hash_update(handle: opaque of sha256, data: string): bool|\\ 379 | Feeds an incremental SHA256 computation with \verb|data|. Call 380 | \verb|sha256_hash_finish(handle)| to retrieve the final hash digest. 381 | \item \verb|sha256_hash_finish(handle: opaque of sha256): string|\\ 382 | Returns the final SHA256 digest of \verb|handle|. This invalidates 383 | \verb|handle|, i.e., the function can only be called once. 384 | \item \verb|strftime(fmt: string, d: time): string|\\ 385 | Formats the time value \verb|d| according to the format string \verb|fmt|. 386 | See \verb|man strftime| for the format of \verb|fmt|. 387 | \item \verb|lookup_addr(host: addr): string|\\ 388 | Issues an asynchronous reverse DNS lookup and delays the function result. 389 | Therefore, it can only be called inside a \verb|when|-condition, e.g., 390 | \verb|when ( local host = lookup_addr(10.0.0.1) ) { f(host); }|. 391 | Returns the DNS name of \verb|host|. 392 | \item \verb|lookup_hostname(host: string): set[addr]|\\ 393 | Issues an asynchronous DNS lookup and delays the function result. 394 | Returns a set containing the addresses that \verb|host| resolves to. 395 | See \verb|lookup_addr| for a usage example. 396 | \item \verb|identify_data(data: string, return_mime: bool): string|\\ 397 | Invokes \texttt{libmagic} on \verb|data| to determine its MIME type. If 398 | \verb|return_mime| is true, the function returns a MIME type string instead 399 | of a textual description. 400 | \item \verb|unique_id(prefix: string): string|\\ 401 | Creates an identifier that is unique with high probability, with 402 | \verb|prefix| prepended to the result. 403 | \item \verb|unique_id_from(pool: int, prefix: string): string|\\ 404 | Same as \verb|unique_id|, except that the additional argument \verb|pool| 405 | specifies a seed for determinism. 406 | \item \verb|terminate(): bool|\\ 407 | Gracefully shuts down Bro by terminating outstanding processing. Returns 408 | true after successful termination and false when Bro is still in the 409 | process of shutting down. 410 | \item \verb|exit(code: int)| 411 | Shuts down the Bro process immediately and returns with \verb|code|. 412 | \end{itemize} 413 | 414 | % Users typically do not interact with the packet filtering directly. 415 | \verbose{ 416 | \subsubsection*{Packet Filtering} 417 | 418 | \begin{itemize} 419 | \item \verb|precompile_pcap_filter(id: PcapFilterID, s: string): bool|\\ 420 | Precompiles the PCAP filter \verb|s| and binds it to the identifier 421 | \verb|id| in \texttt{libpcap}. Returns true if the filter expression is 422 | valid. See \verb|install_pcap_filter|. 423 | \item \verb|install_pcap_filter(id: PcapFilterID): bool|\\ 424 | Installs a PCAP filter precompiled via \verb|precompile_pcap_filter|. 425 | Returns true if the installation succeeds. 426 | \item \verb|install_src_addr_filter(ip: addr, flags: count, p double): bool|\\ 427 | Installs a filter to drop packets from the IP source address \verb|ip| with 428 | probability $\mathtt{p} \in [0,1]$ if none of the TCP flags given by 429 | \verb|flags| are set. 430 | \item \verb|install_src_net_filter(s: subnet, flags: count, p: double): bool|\\ 431 | Same as \verb|install_src_addr_filter| but for subnets instead of IP 432 | addresses. 433 | \item \verb|uninstall_src_addr_filter(ip: addr): bool|\\ 434 | Removes an IP source address filter for \verb|ip| installed with 435 | \verb|install_src_addr_filter|. 436 | \item \verb|uninstall_src_net_filter(snet: subnet): bool|\\ 437 | Removes an IP source subnet filter for \verb|snet| installed with 438 | \verb|install_src_net_filter|. 439 | \item \verb|install_dst_addr_filter(ip: addr, flags: count, p: double): bool|\\ 440 | Same as \verb|install_src_addr_filter| but for IP destination addresses. 441 | \item \verb|install_dst_net_filter(s: snet, flags: count, p: double): bool|\\ 442 | Same as \verb|install_dst_addr_filter| but for subnets instead of IP 443 | addresses. 444 | \item \verb|uninstall_dst_addr_filter(ip: addr): bool|\\ 445 | Removes an IP destination address filter for \verb|ip| installed with 446 | \verb|install_dst_addr_filter|. 447 | \item \verb|uninstall_dst_net_filter(snet: subnet): bool|\\ 448 | Removes an IP destination subnet filter for \verb|snet| installed with 449 | \verb|install_dst_net_filter|. 450 | \item \verb|pcap_error(): string|\\ 451 | Returns a descriptive error message if the last PCAP function failed. 452 | \end{itemize} 453 | } 454 | 455 | \subsubsection*{Introspection} 456 | 457 | \begin{itemize} 458 | \item \verb|bro_version(): string|\\ 459 | Returns the Bro version string. 460 | \item \verb|getpid(): count|\\ 461 | Returns Bro's process ID. 462 | \item \verb|gethostname(): string|\\ 463 | Returns the hostname of the machine Bro runs on. 464 | \item \verb|current_time(): time|\\ 465 | Returns the current wall-clock time. 466 | \verbose{ 467 | In general, you should use \verb|network_time| instead of 468 | \verb|current_time| unless you're using Bro for non-networking uses (such 469 | as general scripting; not particularly recommended), because otherwise your 470 | script may behave very differently on live traffic versus played-back 471 | traffic from a save file. 472 | } 473 | \item \verb|network_time(): time|\\ 474 | Returns the timestamp of the last packet processed. 475 | Returns the timestamp of the most recently read packet, whether read from a 476 | live network interface or from a save file. 477 | \verbose{ 478 | \item \verb|do_profiling()|\\ 479 | Enables detailed collections of statistics about CPU/memory usage, 480 | connections, TCP states/reassembler, DNS lookups, timers, and script-level 481 | state. The script variable \verb|profiling_file| holds the name of the log 482 | file. 483 | \item \verb|net_stats(): NetStats|\\ 484 | Returns statistics about the number of packets 485 | \first received by Bro, 486 | \second dropped, 487 | and \third seen on the link (not always available). 488 | \item \verb|resource_usage(): bro_resources|\\ 489 | Returns Bro process statistics, such as real/user/sys CPU time, memory 490 | usage, page faults, number of TCP/UDP/ICMP connections, timers, and events 491 | queued/dispatched. 492 | \item \verb|get_matcher_stats(): matcher_stats|\\ 493 | Returns statistics about the regular expression engine, such as the number 494 | of distinct matchers, DFA states, DFA state transitions, memory usage of 495 | DFA states, cache hits/misses, and average number of NFA states across all 496 | matchers. 497 | \item \verb|dump_rule_stats(f: file): bool|\\ 498 | Write rule matcher statistics (DFA states, transitions, memory usage, cache 499 | hits/misses) to the file \verb|f|. 500 | \ReturnsTrueOnSuccess 501 | \item \verb|get_gap_summary(): gap_info|\\ 502 | Returns statistics about TCP gaps. 503 | \item \verb|type_name(t: any): string|\\ 504 | Returns the type name of \texttt{t}. 505 | \item \verb|record_type_to_vector(rt: string): vector of string|\\ 506 | Converts the record type name \texttt{rt} into a vector of strings, where 507 | each element is the name of a record field. Nested records are flattened. 508 | \item \verb|global_sizes(): table[string] of count|\\ 509 | Returns a table containing the size of all global variables, where the 510 | index is the variable name and the value the variable size in bytes. 511 | \item \verb|global_ids(): table[string] of script_id|\\ 512 | Returns a table with information about all global identifiers. The table 513 | value is a record containing the type name of the identifier, whether it is 514 | exported, a constant, an enum constant, redefinable, and its value (if it 515 | has one). 516 | \item \verb|lookup_ID(id: string): any|\\ 517 | Returns the value associated with the global identifier \verb|id|. If 518 | \verb|id| does not describe a valid identifier, the function returns the 519 | string \verb|""| or \verb|""|. 520 | \item \verb|record_fields(r: any): table[string] of record_field|\\ 521 | Returns meta data about a record instance \verb|r|, which includes the 522 | type name, whether the field is logged, its value (if it has one), and its 523 | default value (if specified). 524 | \item \verb|reading_live_traffic(): bool|\\ 525 | Checks whether Bro reads traffic from one or more network interfaces (as 526 | opposed to from a network trace in a file). Note that this function returns 527 | true even after Bro has stopped reading network traffic, for example due to 528 | receiving a termination signal. 529 | \item \verb|reading_traces(): bool|\\ 530 | Checks whether Bro reads traffic from a trace file (as opposed to 531 | from a network interface). 532 | \item \verb|bro_is_terminating(): bool|\\ 533 | Returns true if Bro is in the process of shutting down. 534 | } 535 | \item \verb|is_local_interface(ip: addr): bool|\\ 536 | Returns true if the address \verb|ip| is a valid DNS entry for 537 | \texttt{localhost}. 538 | \verbose{ 539 | \item \verb|is_external_connection(c: connection): bool|\\ 540 | Returns true if the connection \verb|c| has been received externally. 541 | Broccoli or the Time Machine can send packets to Bro via a mechanism that 542 | one step lower than sending events. This function returns true if the 543 | \verb|c| stems from one of these other \emph{packet sources}. 544 | \item \verb|disable_print_hook(f: file)|\\ 545 | Function equivalent of the \verb|&disable_print_hook| attribute. In a 546 | distributed setup, communicating Bro instances generate the event 547 | \verb|print_hook| for each print statement and send it to the remote side. 548 | When disabled for a particular file, these events will not be propagated to 549 | other peers. 550 | \item \verb|enable_communication()|\\ 551 | Enables the communication system. By default, communication is off until 552 | explicitly enabled and all other calls to communication-related BiF's will 553 | be ignored until done so. 554 | \item \verb|suspend_processing()|\\ 555 | Stops Bro's packet processing. Used to synchronize distributed trace 556 | processing with communication (\emph{pseudo-realtime} mode). 557 | \item \verb|continue_processing()|\\ 558 | Resumes Bro's packet processing; the counterpart to 559 | \verb|suspend_processing|. 560 | \item \verb|suspend_state_updates()|\\ 561 | Stops propagating \verb|&synchronized| accesses. 562 | \item \verb|resume_state_updates()|\\ 563 | Resumes propagating \verb|&synchronized| accesses; the counterpart to 564 | \verb|suspend_state_udpates|. 565 | \item \verb|enable_event_group(group: string)|\\ 566 | Enables all event handlers in the group \verb|group|. This affects all 567 | handlers that have been tagged with the attribute \verb|&group="group"|. 568 | \item \verb|disable_event_group(group: string)|\\ 569 | Disables all event handlers in the group \verb|group|. This affects all 570 | handlers that have been tagged with the attribute \verb|&group="group"|. 571 | } 572 | \end{itemize} 573 | 574 | \verbose{ 575 | \subsubsection*{Independent State} 576 | 577 | \begin{itemize} 578 | \item \verb|checkpoint_state(): bool|\\ 579 | Flushes in-memory state with the \verb|&persistence| attribute to the state 580 | file \texttt{.state/state.bst}. 581 | \item \verb|rescan_state(): bool|\\ 582 | Reads persistent configuration and state from the \texttt{.state} 583 | directory. 584 | \item \verb|capture_events(filename: string): bool|\\ 585 | Writes the event stream generated by the core to \verb|filename|. Use the 586 | \texttt{-x} command line switch to replay the saved events. 587 | \item \verb|capture_state_updates(filename: string): bool|\\ 588 | Writes state updates generated by \verb|&synchronized| variables to the 589 | file \verb|filename|. 590 | \item \begin{verbatim} 591 | connect(ip: addr, zone_id: string, p: port, our_class: string, retry: interval, 592 | ssl: bool): count 593 | \end{verbatim} 594 | Establishes a connection to a remote Bro instance or Broccoli application 595 | at IP address \verb|ip| and port \verb|p|. If the connection fails, Bro 596 | tries to reconnect with the peer after the time interval \verb|retry|. If 597 | \verb|ssl| is true, the connection uses SSL to encrypt the session. 598 | If \verb|our_class| is a non-empty string, the remote (listening) peer 599 | checks it against its class name in its peer table and terminates the 600 | connection if they don't match. If \verb|ip| is non-global IPv6 address, an 601 | RFC 4007 \verb|zone_id| can be given here. 602 | Returns a locally unique ID of the new peer. 603 | \item \verb|disconnect(p: event_peer): bool|\\ 604 | Disconnects the peer identified by \verb|p|. 605 | \item \begin{verbatim} 606 | listen(ip: addr, p: port, ssl: bool, ipv6: bool, zone_id: string, 607 | retry: interval): bool 608 | \end{verbatim} 609 | Listens on address \verb|ip| and port \verb|p| for remote connections, 610 | retrying after \verb|retry| if \verb|ip| is found to be already in use. If 611 | \verb|ssl| is true, Bro uses SSL to encrypt the session. If \verb|ipv6| is 612 | \verb|true|, also listen on IPv6 addresses with an optional RFC 4007 613 | \verb|zone_id|. 614 | \ReturnsTrueOnSuccess 615 | \item \verb|request_remote_events(p: event_peer, handlers: pattern): bool|\\ 616 | Subscribes to all events from remote peer \verb|p| whose names match the 617 | pattern \verb|handlers|. 618 | %That is, the local Bro instance inserts all events received from \verb|p| 619 | %into its own event queue and dispatches them when they are ready. 620 | \item \verb|request_remote_sync(p: event_peer, auth: bool): bool|\\ 621 | Requests synchronization of IDs with remote peer \verb|p|. If \verb|auth| 622 | is true, the local Bro instance considers its current state authoritative 623 | and sends it to \verb|p| right after the handshake. 624 | \item \verb|request_remote_logs(p: event_peer): bool|\\ 625 | Requests logs from remote peer \verb|p|. 626 | \ReturnsTrueOnSuccess 627 | \item \verb|set_accept_state(p: event_peer, accept: bool): bool|\\ 628 | Sets a boolean flag whether Bro accepts state from the remote peer \verb|p|. 629 | \ReturnsTrueOnSuccess 630 | \item \verb|set_compression_level(p: event_peer, level: count): bool|\\ 631 | Sets the compression level of the session with the remote peer \verb|p|. 632 | values for \verb|level| are in $[0,9]$, where 0 is the default and means no 633 | compression. 634 | \ReturnsTrueOnSuccess 635 | \item \verb|is_remote_event(): bool|\\ 636 | Returns true if the last raised event came from a remote peer. 637 | \item \verb|send_state(p: event_peer): bool|\\ 638 | Sends all persistent state to the remote peer \verb|p|. 639 | \ReturnsTrueOnSuccess 640 | \item \verb|send_id(p: event_peer, id: string): bool|\\ 641 | Sends the global identifier \verb|id| to the remote peer \verb|p|, which 642 | might then install it locally. 643 | \item \verb|terminate_communication(): bool|\\ 644 | Gracefully finishes communication by first making sure that all remaining 645 | data from parent and child has been sent out. 646 | Returns true if the termination process has been started successfully. 647 | \item \verb|complete_handshake(p: event_peer): bool|\\ 648 | Signals the remote peer \verb|p| that the local Bro instance finished the 649 | initial handshake. 650 | \ReturnsTrueOnSuccess 651 | \item \verb|send_ping(p: event_peer, seq: count): bool|\\ 652 | Sends a ping with a sequence number \verb|seq| to the remote peer \verb|p|. 653 | In combination with an event handler for \verb|remote_pong|, this function 654 | can be used to measure latency between two peers. 655 | \ReturnsTrueOnSuccess 656 | \item \verb|send_current_packet(p: event_peer): bool|\\ 657 | Sends the currently processed packet to the remote peer \verb|p|. 658 | \ReturnsTrueOnSuccess 659 | \item \verb|get_event_peer(): event_peer|\\ 660 | Returns the peer who generated the last event. 661 | \item \verb|get_local_event_peer(): event_peer|\\ 662 | Returns the local peer. 663 | \item \verb|send_capture_filter(p: event_peer, s: string): bool|\\ 664 | Sends the capture filter \verb|s| to the remote peer \verb|p|. 665 | \ReturnsTrueOnSuccess 666 | \end{itemize} 667 | } 668 | 669 | \verbose{ 670 | \subsubsection*{Analyzer Behavior} 671 | 672 | \begin{itemize} 673 | \item \verb|current_analyzer(): count|\\ 674 | Returns the ID of the analyzer which raised the current event, or 0 if no 675 | analyzer has been instantiated. 676 | \item \verb|analyzer_name(aid: count): string|\\ 677 | Translates the analyzer ID \verb|aid| to a string representation. 678 | \item 679 | \begin{verbatim} 680 | expect_connection(orig: addr, resp: addr, resp_p: port, 681 | analyzer: count, tout: interval) 682 | \end{verbatim} 683 | Schedules the analyzer identified by the ID \verb|analyzer| for a future 684 | connection from IP address \verb|orig| to \verb|resp| at port 685 | \verb|resp_p|. The function ignores the scheduling request if the 686 | connection did not occur within the specified time interval \verb|tout|. 687 | \item \verb|disable_analyzer(id: conn_id, aid: count): bool|\\ 688 | Disables the analyzer \verb|aid| which raised the current event if it 689 | belongs to connection identified by \verb|id|. 690 | \item \verb|get_login_state(id: conn_id): count|\\ 691 | Returns the state of the given login (Telnet or Rlogin) connection 692 | identified by \texttt{id}. Returns false if the connection is not active 693 | or is not tagged as a login analyzer. Otherwise the function returns the 694 | state, which can be one of: 695 | \begin{itemize} 696 | \item \verb|LOGIN_STATE_AUTHENTICATE|: The connection is in its initial 697 | authentication dialog. 698 | \item \verb|OGIN_STATE_LOGGED_IN|: The analyzer believes the user has 699 | successfully authenticated. 700 | \item \verb|LOGIN_STATE_SKIP|: The analyzer has skipped any further 701 | processing of the connection. 702 | \item \verb|LOGIN_STATE_CONFUSED|: The analyzer has concluded that it 703 | does not correctly know the state of the connection, and/or the 704 | username associated with it. 705 | \end{itemize} 706 | \item \verb|set_login_state(id: conn_id, new_state: count): bool|\\ 707 | Sets the login state of the connection identified by \verb|id| to 708 | \verb|new_state|. See \verb|get_login_state| for potential values of 709 | \verb|new_state|. Returns false if \texttt{id} is not an active connection 710 | or does not tagged as login analyzer, and true otherwise. 711 | \item \verb|skip_further_processing(id: conn_id): bool|\\ 712 | Informs Bro that it should skip any further processing of the contents of 713 | the connection identified by \verb|id|. In particular, Bro will refrain 714 | from reassembling the TCP byte stream and from generating events relating 715 | to any analyzers that have been processing the connection. 716 | Bro will still generate connection-oriented events such as 717 | \verb|connection_finished|. 718 | Returns false if \verb|id| does not point to an active connection and 719 | true otherwise. 720 | Note that this does not in itself imply that packets from 721 | this connection will not be recorded, which is controlled separately by 722 | \verb|set_record_packets|. 723 | \item \verb|set_record_packets(id: conn_id, do_record: bool): bool|\\ 724 | Controls whether packet contents belonging to the connection identified by 725 | \verb|id| should be recorded (when \texttt{-w \textit{out.pcap}} is 726 | provided on the command line). 727 | Note that this is independent of whether Bro processes the packets of this 728 | connection, which is controlled separately by 729 | \verb|skip_further_processing|. 730 | \item \verb|set_contents_file(id: conn_id, direction: count, f: file): bool|\\ 731 | Associates the file handle \verb|f| with the connection identified by 732 | \verb|id| for writing TCP byte stream contents. The argument 733 | \verb|direction| can take one the four values 734 | \verb|CONTENTS_{NONE,ORIG,RESP,BOTH}| and controls what sides of the 735 | connection contents are recorded. 736 | \begin{itemize} 737 | \item \verb|CONTENTS_NONE|: Stop recording the connection's content. 738 | \item \verb|CONTENTS_ORIG|: Record the data sent by the connection 739 | originator (often the client). 740 | \item \verb|CONTENTS_RESP|: Record the data sent by the connection 741 | responder (often the server). 742 | \item \verb|CONTENTS_BOTH|: Record the data sent in both directions. 743 | Results in the two directions being intermixed in the file, in the 744 | order the data was seen by Bro. 745 | \end{itemize} 746 | Returns false if \verb|id| does not point to an active connection and 747 | true otherwise. 748 | Note that the data recorded to the file reflects the byte 749 | stream, not the contents of individual packets. Reordering and duplicates 750 | are removed. If any data is missing, the recording stops at the missing 751 | data; this can happen, e.g., due to an \verb|ack_above_hole| event. 752 | \item \verb|get_contents_file(id: conn_id, direction: count): file|\\ 753 | Returns the file handle associated with the connection identified by 754 | \texttt{id} and \texttt{direction}. If the connection exists but no 755 | contents file for \texttt{direction}, the function returns a handle to new 756 | file. If not active connection for \texttt{id} exists, it returns an error. 757 | \item \verb|skip_http_entity_data(c: connection, is_orig: bool)|\\ 758 | Skips the data of the HTTP entity in the connection \texttt{c}. If 759 | \verb|is_orig| is true, the client data is skipped and the server data 760 | otherwise. 761 | \item \verb|skip_smtp_data(c: connection)|\\ 762 | Skips SMTP data until the next email in \texttt{c}. 763 | \item \verb|dump_current_packet(file_name: string): bool|\\ 764 | Writes the current packet to the file identified by \verb|file_name|. 765 | \ReturnsTrueOnSuccess 766 | \item \verb|get_current_packet(): pcap_packet|\\ 767 | Returns the currently processed PCAP packet, which is a record containing 768 | the timestamp, ``snaplen,'' and packet data. 769 | \item \verb|dump_packet(pkt: pcap_packet, file_name: string): bool|\\ 770 | Writes the packet \verb|pkt| to the file identified by \verb|file_name|. 771 | \ReturnsTrueOnSuccess 772 | \item \verb|set_inactivity_timeout(id: conn_id, t: interval): interval|\\ 773 | Sets an individual inactivity timeout for the connection identified by 774 | \texttt{id} (overrides the global inactivity timeout). 775 | Returns the previous timeout interval. 776 | \end{itemize} 777 | } 778 | 779 | \subsubsection*{Files and Directories} 780 | 781 | \begin{itemize} 782 | \item \verb|open(f: string): file|\\ 783 | Opens the file identified by \texttt{f} for writing. Returns a handle 784 | for subsequent file operations. 785 | \item \verb|open_for_append(f: string): file|\\ 786 | Same as \texttt{open}, except that \texttt{f} is not overwritten and 787 | content is appended at the end of the file. 788 | \item \verb|close(f: file): bool|\\ 789 | Closes the file handle \texttt{f} and flushes buffered content. Returns 790 | true on success. 791 | \item \verb|active_file(f: file): bool|\\ 792 | Checks whether \texttt{f} is open. 793 | \item \verb|write_file(f: file, data: string): bool|\\ 794 | Writes \texttt{data} to \texttt{f}. Returns true on success. 795 | \item \verb|file_size(f: string): double|\\ 796 | Returns the file size in bytes of the file identified by \verb|f|. 797 | \item \verb|get_file_name(f: file): string|\\ 798 | Returns the filename associated with \texttt{f}. 799 | \item \verb|set_buf(f: file, buffered: bool)|\\ 800 | Alters the buffering behavior of \texttt{f}. When \texttt{buffered} is 801 | true, the file is fully buffered, i.e., bytes are saved in a buffered until 802 | the block size has been reached. When \texttt{buffered} is false, the file 803 | is line buffered, i.e., bytes are saved up until a newline occurs. 804 | \item \verb|flush_all(): bool|\\ 805 | Flushes all open files to disk. 806 | Returns true when the operations(s) succeeded. 807 | \item \verb|mkdir(f: string): bool|\\ 808 | Creates a new directory identified by \verb|f|. Returns true if the 809 | operation succeeds and false if the creation fails or if \verb|f| exists 810 | already. 811 | \item \verb|enable_raw_output(f: file)|\\ 812 | Function equivalent to the \verb|&raw_output| attribute, which prevents 813 | escaping of non-ASCII characters when writing to \verb|f|. 814 | \verbose{ 815 | \item \verb|rotate_file(f: file)|\\ 816 | Rotates the file \verb|f|. Returns rotation statistics which include the 817 | original file name, the name after the rotation, and the time when \verb|f| 818 | was opened/closed. 819 | \item \verb|rotate_file_by_name(f: string)|\\ 820 | Same as \verb|rotate_file|, but uses the filename rather than the handle to 821 | identify the file. 822 | \item \verb|calc_next_rotate(i: interval): interval|\\ 823 | Calculates the duration until the next time a file is to be rotated based 824 | on the given rotate interval \verb|i|. 825 | } 826 | \end{itemize} 827 | 828 | \subsubsection*{Generic Programming} 829 | 830 | \begin{itemize} 831 | \verbose{ 832 | \item \verb|same_object(o1: any, o2: any): bool|\\ 833 | Checks whether \texttt{o1} and \texttt{o2} reference the same internal 834 | object. 835 | \item \verb|val_size(v: any): count|\\ 836 | Returns the number bytes that \verb|v| occupies in memory. 837 | } 838 | \item \verb|length(v: any): count|\\ 839 | Returns the number of elements in the container \texttt{v}. 840 | \item \verb|clear_table(v: any)|\\ 841 | Removes all elements from the set or table \texttt{v}. 842 | \item \verb|resize(v: any, newsize: count): count|. 843 | Resizes the vector \verb|v| to the size \verb|newsize|. 844 | Returns the old size of \verb|v| and 0 if \verb|v| is not a \verb|vector| 845 | type. 846 | \item \verb|any_set(v: any): bool|\\ 847 | Tests whether the boolean vector (\verb|vector of bool|) has any true 848 | element, i.e., checks whether $\exists x \in \mathtt{v}: x = \mathtt{T}$. 849 | \item \verb|all_set(v: any): bool|\\ 850 | Tests whether all elements of the boolean vector (\verb|vector of bool|) are 851 | true, i.e., checks whether $\forall x \in \mathtt{v}: x = \mathtt{T}$. 852 | Missing elements count as false. 853 | \item \verb|sort(v: any, ...): any|\\ 854 | Sorts the vector \verb|v| in place and returns the original vector. 855 | The second argument is a comparison function that takes two arguments: if 856 | the type of \verb|v| is \verb|vector of T|, then the comparison function 857 | must be \verb|function(a: T, b: T): bool|, which returns \verb|a < b| for 858 | some type-specific notion of the less-than operator. 859 | \item \verb|order(v: any, ...): vector of count|\\ 860 | Returns the order of the elements in the vector \verb|v| according to some 861 | comparison function. See \verb|sort|. 862 | \end{itemize} 863 | 864 | \subsubsection*{Math} 865 | 866 | \begin{itemize} 867 | \item \verb|floor(x: double): double|\\ 868 | Chops off any decimal digits of \texttt{x}, 869 | i.e., computes $\lfloor\mathtt{x}\rfloor$. 870 | \item \verb|sqrt(x: double): double|\\ 871 | Returns the square root of \texttt{x}, i.e., computes $\sqrt{\mathtt{x}}$. 872 | \item \verb|exp(x: double): double|\\ 873 | Raises $e$ to the power of \texttt{x}, i.e., computes $e^\mathtt{x}$. 874 | \item \verb|ln(x: double): double|\\ 875 | Returns the natural logarithm of \texttt{x}, 876 | i.e., computes $\ln \mathtt{x}$. 877 | \item \verb|log10(x: double): double|\\ 878 | Returns the common logarithm of \texttt{x}, 879 | i.e., computes $\log_{10} \mathtt{x}$. 880 | \end{itemize} 881 | 882 | \subsubsection*{String Processing} 883 | 884 | \begin{itemize} 885 | \item \verb|byte_len(s: string): count|\\ 886 | Returns the number of characters (i.e., bytes) in \texttt{s}. This 887 | includes any embedded NULs, and also a trailing NUL, if any (which is why 888 | the function isn't called \verb|strlen|; to remind the user that Bro 889 | strings can include NULs). 890 | \item \verb|sub_bytes(s: string, start: count, n: int): string|\\ 891 | Extracts a substring of \texttt{s}, starting at position \texttt{start} and 892 | having length \texttt{n}. 893 | \item \verb|split(s: string, re: pattern): table[count] of string|\\ 894 | Splits \texttt{s} into an array using \texttt{re} to separate the elements. 895 | The returned table starts at index 1. Note that conceptually the return 896 | value is meant to be a vector and this might change in the future. 897 | \item \verb|split1(s: string, re: pattern): table[count] of string|\\ 898 | Same as \texttt{split}, but \texttt{s} is only split once (if possible) at 899 | the earliest position and an array of two strings is returned. An array of 900 | one string is returned when \texttt{s} cannot be split. 901 | \item \verb|split_all(s: string, re: pattern): table[count] of string|\\ 902 | Same as \texttt{split}, but also include the matching separators, e.g., 903 | \verb|split_all("a-b--cd", /(\-)+/)| returns 904 | \verb|{"a", "-", "b", "--", "cd"}|. Odd-indexed elements do not match the 905 | pattern and even-indexed ones do. 906 | \item 907 | \begin{verbatim} 908 | split_n(s: string, re: pattern, incl_sep: bool, 909 | max_num_sep: count): table[count] of string 910 | \end{verbatim} 911 | Similar to \verb|split1| and \verb|split_all|, but \verb|incl_sep| 912 | indicates whether to include matching separators and \verb|max_num_sep| the 913 | number of times to split \texttt{s}. 914 | \item \verb|str_split(s: string, idx: vector of count): vector of string|\\ 915 | Splits \texttt{s} into substrings, taking all the indices in 916 | \texttt{idx} as cutting points; \texttt{idx} does not need to be sorted and 917 | out-of-bounds indices are ignored. 918 | \item \verb|string_cat(...): string|\\ 919 | Concatenes a variable number of string arguments into a single string. 920 | \item \verb|cat_string_array(a: table[count] of string): string|\\ 921 | Same as \verb|string_cat|, except that it takes an array of strings as 922 | argument and concatenates its values into a single string. 923 | \item 924 | \begin{verbatim} 925 | cat_string_array_n(a: table[count] of string, 926 | start: count, end: count): string 927 | \end{verbatim} 928 | Same as \verb|cat_string_array|, but only concatenates the strings from 929 | index \verb|start| to \verb|end|. 930 | \item 931 | \begin{verbatim} 932 | join_string_array(sep: string, a: table[count] of string): string 933 | \end{verbatim} 934 | Concatenates all elements in \verb|a| into a single string, 935 | with \verb|sep| placed between each element. 936 | \item \verb|join_string_vec(v: vector of string, sep: string): string|\\ 937 | Concatenates all elements in \verb|v| into a single string, 938 | with \verb|sep| placed between each element. 939 | \item \verb|sort_string_array(a: table[count] of string): string|\\ 940 | Sorts the string array \verb|a| and returns a sorted copy. 941 | \item \verb|sub(s: string, re: pattern, repl: string): string|\\ 942 | Substitutes \texttt{repl} for the first occurrence of \texttt{re} in 943 | \texttt{s}. 944 | \item \verb|gsub(s: string, re: pattern, repl: string): string|\\ 945 | Same as \texttt{sub} except that \emph{all} occurrences of \texttt{re} are 946 | replaced. 947 | \item \verb|strcmp(s1: string, s2: string): int| 948 | Lexicographically compares \texttt{s1} and \texttt{s2}. Returns an integer 949 | greater than, equal to, or less than 0 according as \texttt{s1} is greater 950 | than, equal to, or less than \texttt{s2}. 951 | \item \verb|strstr(big: string, little: string): count|\\ 952 | Locates the first occurrence of \texttt{little} in \texttt{big}. 953 | Returns 0 if \texttt{little} is not found in \texttt{big}. 954 | \item \verb|subst_string(s: string, from: string, to: string): string|\\ 955 | Substitutes each (non-overlapping) appearance of \texttt{from} in 956 | \texttt{s} to \texttt{to}, and return the resulting string. 957 | \item \verb|to_lower(s: string): string|\\ 958 | Returns a copy of the given string with the uppercase letters (as indicated 959 | by \verb|isascii| and \verb|isupper|) folded to lowercase (via 960 | \verb|tolower|). 961 | \item \verb|to_upper(s: string): string|\\ 962 | Returns a copy of \verb|s| with the lowercase letters (as indicated by 963 | \verb|isascii| and \verb|islower|) folded to lowercase (via 964 | \verb|toupper|). 965 | \item \verb|is_ascii(s: string): bool|\\ 966 | Returns false if any byte value of \texttt{s} is greater than 127, and true 967 | otherwise. 968 | \item \verb|edit(s: string, edit_char: string): string|\\ 969 | Returns a version of \verb|s| assuming that \verb|edit_char| is the 970 | ``backspace character'' (usually \verb|\x08| for backspace or \verb|\x7f| 971 | for DEL). For example, \verb|edit("hello there", "e")| returns 972 | \verb|"llo t"|. The argument \verb|edit_char| must be a string of exactly 973 | one character, or Bro generates a run-time error and uses the first 974 | character in the string. 975 | \item \verb|clean(s: string): string|\\ 976 | Replaces non-printable characters in \texttt{s} with escaped sequences, 977 | with the mappings 978 | \verb|NUL| $\rightarrow$ \verb|\0|, 979 | \verb|DEL| $\rightarrow$ \verb|^?|, 980 | values $\le 26$ $\rightarrow$ \verb|^[A-Z]|, 981 | and values not in $[32, 126]$~$\rightarrow$~\verb|%XX|. If the string does 982 | not yet have a trailing NUL, one is added. 983 | \item \verb|to_string_literal(s: string): string|\\ 984 | Same as clean, but with different mappings: 985 | values not in $[32, 126]$~$\rightarrow$~\verb|%XX|, 986 | \verb|\|~$\rightarrow$~\verb|\\|, 987 | \verb|'|~$\rightarrow$~\verb|\'|, 988 | \verb|"|~$\rightarrow$~\verb|\"|. 989 | \item \verb|escape_string(s: string): string|\\ 990 | Returns a printable version of \texttt{s}. Same as \texttt{clean} except 991 | that non-printable characters are removed. 992 | \item \verb|string_to_ascii_hex(s: string): string|\\ 993 | Returns an ASCII hexadecimal representation of a string. 994 | \item \verb|strip(s: string): string|\\ 995 | Strips whitespace at both ends of \texttt{s}. 996 | \item \verb|string_fill(len: int, source: string): string|\\ 997 | Generates a string of size \texttt{len} and fills it with repetitions of 998 | \texttt{source}. 999 | \item \verb|str_shell_escape(source: string): string|\\ 1000 | Takes a string and escapes characters that would allow execution of 1001 | commands at the shell level. Must be used before including strings in 1002 | \verb|system| or similar calls. 1003 | \item \verb|find_all(s: string, re: pattern): set of string|\\ 1004 | Returns all occurrences of \texttt{re} in \texttt{s} (or an empty empty set 1005 | if none). 1006 | \item \verb|find_last(s: string, re: pattern): string|\\ 1007 | Returns the last occurrence of \texttt{re} in \texttt{s}. If not found, 1008 | returns an empty string. Note that this function returns the match that 1009 | starts at the largest index in the string, which is not necessarily the 1010 | longest match. For example, a pattern of \texttt{/.*/} will return the 1011 | final character in the string. 1012 | \item \verb|hexdump(data: string): string|\\ 1013 | Returns a hex dump for \texttt{data}. The hex dump renders 16 bytes per 1014 | line, with hex on the left and ASCII (where printable) on the right. Based 1015 | on Netdude's hex editor code. 1016 | \item \verb|find_entropy(data: string): entropy_test_result|\\ 1017 | Performs an \href{http://www.fourmilab.ch/random/}{entropy} 1018 | test on \verb|data|. 1019 | \verbose{ 1020 | The result is a record with the following fields: 1021 | \begin{itemize} 1022 | \item \verb|entropy|: The information density expressed as a number of 1023 | bits per character. 1024 | \item \verb|chi_square|: The $\chi^2$ test value expressed as an absolute 1025 | number and a percentage which indicates how frequently a truly random 1026 | sequence would exceed the value calculated, i.e., the degree to which 1027 | the sequence tested is suspected of being non-random. 1028 | If the percentage is greater than 99\% or less than 1\%, the sequence 1029 | is almost certainly not random. If the percentage is between 99\% and 1030 | 95\% or between 1\% and 5\%, the sequence is suspect. Percentages 1031 | between 90\% and 95\% and 5\% and 10\% indicate the sequence is 1032 | ``almost suspect.'' 1033 | \item \verb|mean|: The arithmetic mean of all the bytes. If the data are 1034 | close to random, it should be around 127.5. 1035 | \item \verb|monte_carlo_pi|: Each successive sequence of six bytes is 1036 | used as 24-bit $x$ and $y$ coordinates within a square. If the 1037 | distance of the randomly-generated point is less than the radius of a 1038 | circle inscribed within the square, the six-byte sequence is considered 1039 | a ``hit.'' The percentage of hits can be used to calculate the value of 1040 | $\pi$. For very large streams the value will approach the correct value 1041 | of $\pi$ if the sequence is close to random. 1042 | \item \verb|serial_correlation|: This quantity measures the extent to 1043 | which each byte in the file depends upon the previous byte. For random 1044 | sequences this value will be close to zero. 1045 | \end{itemize} 1046 | } 1047 | \item \verb|entropy_test_init(): opaque of entropy|\\ 1048 | Retrieves a data structures for incremental entropy calculation. 1049 | \ReturnsTrueOnSuccess 1050 | See \verb|entropy_test_add| and \verb|entropy_test_finish|. 1051 | \item \verb|entropy_test_add(handle: opaque of entropy, data: string): bool|\\ 1052 | Adds \verb|data| to the incremental entropy calculation identified by 1053 | \verb|handle|. 1054 | \ReturnsTrueOnSuccess 1055 | \item \verb|entropy_test_finish(handle: opaque of entropy): entropy_test_result|\\ 1056 | Finalizes the incremental entropy calculation identified by \verb|handle|. 1057 | \verbose{ 1058 | When all data has been added, this function returns the result record which 1059 | is described above in \verb|find_entropy|. 1060 | } 1061 | \end{itemize} 1062 | 1063 | \subsubsection*{Network Type Processing} 1064 | 1065 | \begin{itemize} 1066 | \item \verb|is_v4_addr(a: addr): bool|\\ 1067 | Checks whether an address is IPv4. Returns \verb|true| for IPv4 and 1068 | \verb|false| for IPv6 addresses. 1069 | \item \verb|is_v6_addr(a: addr): bool|\\ 1070 | Checks whether an address is IPv6. Returns the opposite of 1071 | \verb|is_v4_addr|. 1072 | \item \verb|mask_addr(a: addr, top_bits_to_keep: count): subnet|\\ 1073 | Returns the address \verb|a| masked down to the number of upper bits 1074 | indicated by \verb|top_bits_to_keep|, which must be greater than 0 and less 1075 | than 33. For example, \verb|mask_addr(1.2.3.4, 18)| returns \verb|1.2.0.0|, 1076 | and \verb|mask_addr(1.2.255.4, 18)| returns \verb|1.2.192.0|. 1077 | \item \verb|remask_addr(a1: addr, a2: addr, top_bits_from_a1: count): count|\\ 1078 | Takes some top bits (e.g., subnet address) from \texttt{a1} and the other 1079 | bits (intra-subnet part) from \texttt{a2} and merges them to get a new 1080 | address. This is useful for anonymizing at subnet level while preserving 1081 | serial scans. 1082 | \item \verb|is_tcp_port(p: port): bool|\\ 1083 | Checks whether \texttt{p} is a TCP port. 1084 | \item \verb|is_udp_port(p: port): bool|\\ 1085 | Checks whether \texttt{p} is a UDP port. 1086 | \item \verb|is_icmp_port(p: port): bool|\\ 1087 | Checks whether \texttt{p} is an ICMP port. 1088 | \item \verb|connection_exists(id: conn_id): bool|\\ 1089 | Checks whether the connection identified by \texttt{id} is (still) active. 1090 | \item \verb|lookup_connection(id: conn_id): connection|\\ 1091 | Returns the \texttt{connection} record for \texttt{id}. If 1092 | \texttt{id} does not point to an existing connection, the function 1093 | generates a run-time error and returns a dummy value. 1094 | \verbose{ 1095 | \item \verb|get_conn_transport_proto(id: conn_id): transport_proto|\\ 1096 | Returns the transport protocol of the connection identified by \texttt{id}. 1097 | \item \verb|get_port_transport_proto(p: port): transport_proto|\\ 1098 | Returns the transport protocol of \texttt{p}. 1099 | \item \verb|get_orig_seq(id: conn_id): count|\\ 1100 | Returns the highest sequence number sent by a connection's originator, or 0 1101 | if \verb|id| does not point to an active TCP connection. Sequence numbers 1102 | are absolute (i.e., they reflect the values seen directly in packet 1103 | headers; they are not relative to the beginning of the connection). 1104 | \item \verb|get_resp_seq(id: conn_id): count|\\ 1105 | Returns the highest sequence number sent by a connection's responder, or 0 1106 | if \verb|id| does not point to an active TCP connection. 1107 | } 1108 | \item \verb|unescape_URI(URI: string): string|\\ 1109 | Unescapes all characters in \texttt{URI}, i.e., decodes every \verb|%xx| 1110 | group. 1111 | % TODO: wait for answer on bro-dev about these functions. 1112 | % \item \verb|preserve_prefix(a: addr, width: count)|\\ 1113 | % \item \verb|preserve_subnet(sn: subnet)|\\ 1114 | % \item \verb|anonymize_addr(a: addr, cl: IPAddrAnonymizationClass): addr|\\ 1115 | \item \verb|lookup_location(a: addr) : geo_location|\\ 1116 | Performs a geo-lookup of the IP address \verb|a|. Returns country, region, 1117 | city, latitude, and longitude. Needs Bro to built with \texttt{libgeoip}. 1118 | \item \verb|lookup_asn(a: addr): count|\\ 1119 | Performs an AS lookup of the IP address \verb|a|. 1120 | Needs \texttt{libgeoip}. 1121 | \item 1122 | \verbose{ 1123 | \begin{verbatim} 1124 | x509_verify(der_cert: string, cert_stack: vector of string, 1125 | root_certs: table[string] of string): count 1126 | \end{verbatim} 1127 | Verifies the X.509 certificate in DER format given by \verb|der_cert|. The 1128 | argument \verb|cert_stack| specifies a certificate chain to validate 1129 | against, with index 0 typically being the root CA. Bro uses the Mozilla 1130 | root CA list by default; \verb|root_certs| extends that list with 1131 | additional root certificates. 1132 | \item \verb|x509_err2str(err_num: count): string|\\ 1133 | Converts the X.509 certificate verification error code \verb|err_num| into 1134 | a string representation. 1135 | } 1136 | \end{itemize} 1137 | 1138 | \subsubsection*{Conversion} 1139 | 1140 | \begin{itemize} 1141 | \item \verb|cat(...): string|\\ 1142 | Returns the concatenation of the string representation of its arguments, 1143 | which can be of any type. For example, \verb|cat("foo", 3, T)| returns 1144 | \verb|"foo3T"|. 1145 | \item \verb|cat_sep(sep: string, default: string, ...): string|\\ 1146 | Similar to cat, but places \texttt{sep} between each given argument. 1147 | If any of the variable arguments is an empty string it is replaced by 1148 | \texttt{default} instead. 1149 | \item \verb|fmt(...): string|\\ 1150 | Produces a formatted string à la \verb|printf|. 1151 | \verbose{ 1152 | The first argument is the \emph{format string} and specifies how subsequent 1153 | arguments are converted for output. It is composed of zero or more 1154 | directives: ordinary characters (not \verb|%|), which are copied unchanged 1155 | to the output, and conversion specifications, each of which fetches zero or 1156 | more subsequent arguments. Conversion specifications begin with \verb|%| 1157 | and the arguments must properly correspond to the specifier. 1158 | After the \verb|%|, the following characters may appear in sequence: 1159 | \begin{tabular}{l l} 1160 | \verb|%| & Literal \verb|%|\\ 1161 | \verb|-| & Left-align field\\ 1162 | \verb|[0-9]+| & The field width (< 128)\\ 1163 | \verb|.| & Precision of floating point specifiers \verb|[efg]| (< 128)\\ 1164 | \verb|A| & Escape NUL bytes, i.e., replace \verb|0| with \verb|\0|\\ 1165 | \verb|[DTdxsefg]| & 1166 | \begin{minipage}[t]{\linewidth} 1167 | Format specifier\\ 1168 | \begin{tabular}{l p{.7\linewidth}} 1169 | \texttt{[DT]} & ISO timestamp with microsecond precision\\ 1170 | \texttt{d} & Signed/Unsigned integer (using C-style 1171 | \verb|%lld|/\verb|%llu| for \texttt{int}/\texttt{count})\\ 1172 | \texttt{x} & Unsigned hexadecimal (using C-style \verb|%llx|); 1173 | addresses/ports are converted to host-byte order\\ 1174 | \texttt{s} & Escaped string\\ 1175 | \texttt{[efg]} & Double\\ 1176 | \end{tabular} 1177 | \end{minipage}\\ 1178 | \end{tabular} 1179 | } 1180 | Given no arguments, \verb|fmt| returns an empty string. Given a non-string 1181 | first argument, \verb|fmt| returns the concatenation of all its arguments, 1182 | per \verb|cat|. Finally, given the wrong number of additional arguments for 1183 | the given format specifier, \verb|fmt| generates a run-time error. 1184 | \item \verb|to_int(s: string): int|\\ 1185 | Converts a \texttt{string} into a (signed) integer. 1186 | \item \verb|int_to_count(n: int): count|\\ 1187 | Converts a positive integer into a \texttt{count} or returns 0 if 1188 | \texttt{n < 0}. 1189 | \item \verb|double_to_count(d: double): count|\\ 1190 | Converts a positive \texttt{double} into a \texttt{count} or returns 0 if 1191 | \texttt{d < 0.0}. 1192 | \item \verb|to_count(s: string): count|\\ 1193 | Converts a \texttt{string} into a \texttt{count}. 1194 | \item \verb|to_double(s: string): double|\\ 1195 | Converts a \texttt{string} into a \texttt{double}. 1196 | \item \verb|interval_to_double(i: interval): double|\\ 1197 | Converts an \texttt{interval} time span into a \texttt{double}. 1198 | \item \verb|double_to_interval(d: double): interval|\\ 1199 | Converts a \texttt{double} into an \texttt{interval}. 1200 | \item \verb|time_to_double(t: time): double|\\ 1201 | Converts a \texttt{time} value into a \texttt{double}. 1202 | \item \verb|double_to_time(d: double): time|\\ 1203 | Converts a \texttt{double} into a \texttt{time} value. 1204 | \item \verb|double_to_time(d: double): time|\\ 1205 | Converts a \texttt{double} into a \texttt{time} value. 1206 | \item \verb|port_to_count(p: port): count|\\ 1207 | Returns the port number of \texttt{p} as \texttt{count}. 1208 | \item \verb|count_to_port(num: count, t: transport_proto): port|\\ 1209 | Creates a \texttt{port} with number \texttt{num} and transport protocol 1210 | \texttt{t}. 1211 | \item \verb|to_port(s: string): port|\\ 1212 | Converts a \texttt{string} into a \texttt{port}. 1213 | \item \verb|count_to_v4_addr(ip: count): addr|\\ 1214 | Converts an unsigned integer into an IP address. 1215 | \item \verb|to_addr(ip: string): addr|\\ 1216 | Converts a \texttt{string} into an IP address. 1217 | \item \verb|raw_bytes_to_v4_addr(b: string): addr|\\ 1218 | Converts a \texttt{string} of bytes into an IP address. It interprets the 1219 | first 4 bytes of \texttt{b} as an IPv4 address in network order. 1220 | \item \verb|ptr_name_to_addr(s: string): addr|\\ 1221 | Converts a reverse pointer name to an address, e.g., 1222 | \verb|1.0.168.192.in-addr.arpa| to \verb|192.168.0.1|. 1223 | \item \verb|addr_to_ptr_name(a: addr): string|\\ 1224 | Converts an IP address to a reverse pointer name, e.g., 1225 | \verb|192.168.0.1| to \verb|1.0.168.192.in-addr.arpa|. 1226 | \item \verb|addr_to_counts(a: addr): vector of count|\\ 1227 | Converts an IP address into a vector of of \verb|count|s in host 1228 | byte-order. Returns 4 elements for IPv6 and one for IPv4 addresses. 1229 | \item \verb|counts_to_addr(v: vector of count): addr|\\ 1230 | The dual to \verb|addr_to_counts|: converts a vector of counts to and IP 1231 | address. 1232 | \item \verb|to_subnet(ip: string): subnet|\\ 1233 | Converts a \verb|string| into a subnet type. Returns \verb|../0| if the 1234 | input does not parse correctly. 1235 | \verbose{ 1236 | \item \verb|routing0_data_to_addrs(s: string): vector of address|\\ 1237 | Converts the \verb|data| field of \verb|ip6_routing| records (\verb|s|) 1238 | that have \verb|rtype| of 0 into a vector of addresses. 1239 | \item \verb|parse_ftp_port(s: string): ftp_port|\\ 1240 | Converts a string representation of the FTP PORT command to an 1241 | \verb|ftp_port|, 1242 | e.g., \verb|"10,0,0,1,4,31"| to \verb|[h=10.0.0.1, p=1055/tcp, valid=T]| 1243 | \item \verb|parse_eftp_port(s: string): ftp_port|\\ 1244 | Same as as \verb|parse_ftp_port|, but instead for EPRT 1245 | (see~\href{http://tools.ietf.org/html/rfc2428}{RFC 2428}) whose format is 1246 | \verb|EPRT|, where 1247 | \verb|| is a delimiter in the ASCII range 33-126 (usually \verb#|#). 1248 | \item \verb|parse_ftp_pasv(s: string): ftp_port|\\ 1249 | Converts the result of the FTP PASV command to an \verb|ftp_port|. 1250 | \item \verb|parse_ftp_epsv(s: string): ftp_port|\\ 1251 | Same as \verb|parse_ftp_pasv|, but instead for the EPSV 1252 | (see~\href{http://tools.ietf.org/html/rfc2428}{RFC 2428}) whose format is 1253 | \verb| ()|, where \verb|| is a delimiter in 1254 | the ASCII range 33-126 (usually \verb#|#). 1255 | \item \verb|fmt_ftp_port(a: addr, p: port): string|\\ 1256 | Formats the IP address \texttt{a} and TCP port \texttt{p} as an FTP 1257 | PORT command, e.g., \verb|10.0.0.1| and \verb|1055/tcp| to 1258 | \verb|"10,0,0,1,4,31"|. 1259 | \item \verb|decode_netbios_name(name: string): string|\\ 1260 | Decodes a \href{http://support.microsoft.com/kb/194203}{NetBIOS name}, e.g., 1261 | \verb|"FEEIEFCAEOEFFEECEJEPFDCAEOEBENEF"| to \verb|"THE NETBIOS NAME"|. 1262 | \item \verb|decode_netbios_name_type(name: string): count|\\ 1263 | Converts the \href{http://support.microsoft.com/kb/163409}{NetBIOS name 1264 | type} to the corresponding numeric value. 1265 | } 1266 | \item \verb|bytestring_to_hexstr(bytestring: string): string|\\ 1267 | Converts a string of bytes into its hexadecimal representation, e.g., 1268 | \verb|"04"| to \verb|"3034"|. 1269 | \item \verb|decode_base64(s: string): string|\\ 1270 | Decodes the Base64-encoded string \verb|s|. 1271 | \item \verb|decode_base64_custom(s: string, a: string): string|\\ 1272 | Decodes the Base64-encoded string \verb|s| with alphabet \verb|a|. 1273 | \item \verb|uuid_to_string(uuid: string): string|\\ 1274 | Converts a bytes representation of a 1275 | \href{http://en.wikipedia.org/wiki/Universally_unique_identifier}{UUID} to 1276 | its string form, e.g., to \verb|550e8400-e29b-41d4-a716-446655440000|. 1277 | \item \verb|merge_pattern(p1: pattern, p2: pattern): pattern|\\ 1278 | Merges and compiles the regular expressions \verb|p1| and \verb|p2| at 1279 | initialization time (e.g., in the event \verb|bro_init()|). 1280 | \item \verb|convert_for_pattern(s: string): string|\\ 1281 | Escapes \verb|s| so that it is a valid pattern and can be used with the 1282 | \verb|string_to_pattern|. Concretly, any character 1283 | from the set \verb#^$-:"\/|*+?.(){}[]# is prefixed with \verb|\|. 1284 | \item \verb|string_to_pattern(s: string, convert: bool): pattern|\\ 1285 | Converts \verb|s| into a pattern. If \verb|convert| is true, \verb|s| is 1286 | first passed through the function \verb|convert_for_pattern| to escape 1287 | special characters of patterns. 1288 | \verbose{ 1289 | \item \verb|file_mode(mode: count): string|\\ 1290 | Converts UNIX file permissions given by \verb|mode| to a string 1291 | representation of the form \verb|rw[xsS]rw[xsS]rw[xtT]|. 1292 | } 1293 | \end{itemize} 1294 | 1295 | \end{multicols*} 1296 | 1297 | \end{document} 1298 | -------------------------------------------------------------------------------- /cprotect.sty: -------------------------------------------------------------------------------- 1 | %% 2 | %% This is file `cprotect.sty', 3 | %% generated with the docstrip utility. 4 | %% 5 | %% The original source files were: 6 | %% 7 | %% cprotect.dtx (with options: `package') 8 | %% ---------------------------------------------------------------- 9 | %% cprotect --- verbatim in macro arguments 10 | %% E-mail: blflatex@gmail.com 11 | %% Released under the LaTeX Project Public License v1.3c or later 12 | %% See http://www.latex-project.org/lppl.txt 13 | %% ---------------------------------------------------------------- 14 | %% 15 | \NeedsTeXFormat{LaTeX2e} 16 | \ProvidesPackage{cprotect}[2011/01/27 v1.0e (Bruno Le Floch)] 17 | \RequirePackage{ifthen} 18 | \RequirePackage{suffix} 19 | \def\CPT@qend{\CPT@qend} 20 | \def\CPT@option@head#1=#2\CPT@qend{#1} 21 | \def\CPT@option@tail#1=#2\CPT@qend{#2} 22 | \DeclareOption*{% 23 | \ifthenelse{% 24 | \equal{gobbling-escape}{% 25 | \expandafter\CPT@option@head\CurrentOption=\CPT@qend}% 26 | }{% 27 | \edef\CPT@gobbling@escape{% 28 | \expandafter\CPT@option@tail\CurrentOption\CPT@qend 29 | }% 30 | }{% 31 | \ifthenelse{% 32 | \equal{gobbling-letter}{% 33 | \expandafter\CPT@option@head\CurrentOption=\CPT@qend}% 34 | }{% 35 | \edef\CPT@gobbling@letter{% 36 | \expandafter\CPT@option@tail\CurrentOption\CPT@qend 37 | }% 38 | }{% 39 | \PackageError{cprotect}{Unknown option \CurrentOption}{}% 40 | }% 41 | }% 42 | } 43 | \def\CPT@gobbling@escape{E} 44 | \def\CPT@gobbling@letter{L} 45 | \ProcessOptions\relax 46 | \newwrite\CPT@WriteOut 47 | \newcounter{CPT@WriteCount} 48 | \edef\CPT@filename{\jobname.cpt} 49 | \newcommand{\CPT@Write}[1]{% 50 | \immediate\openout\CPT@WriteOut=\CPT@filename% 51 | \newlinechar`\^^M% 52 | \immediate\write\CPT@WriteOut{#1}% 53 | \immediate\closeout\CPT@WriteOut% 54 | \expandafter\xdef\csname CPT@\CPT@filename\endcsname{% 55 | \noexpand\scantokens{#1}% 56 | }% 57 | %\expandafter\gdef\csname \string\CPT@\CPT@filename\expandafter\endcsname\expandafter{% 58 | % \expandafter\protect\csname CPT@\CPT@filename\endcsname}% 59 | %\expandafter\show\csname \string\CPT@\CPT@filename\endcsname% 60 | %\expandafter\show\csname CPT@\CPT@filename\endcsname% 61 | } 62 | \newcommand{\makeallother}{% 63 | \count0=0\relax 64 | \loop 65 | \catcode\count0=12\relax 66 | \advance\count0 by 1\relax 67 | \ifnum\count0<256 68 | \repeat 69 | } 70 | { 71 | \catcode`\/=0 72 | /catcode`/\=12 73 | /catcode`/^=12 74 | /xdef/CPT@escape@hat@hat@L{\^^/CPT@gobbling@letter/space} 75 | /xdef/CPT@escape@hat@hat@E{\^^/CPT@gobbling@escape/space} 76 | /xdef/CPT@hat@hat@E@hat@hat@L{% 77 | ^^/CPT@gobbling@escape^^/CPT@gobbling@letter/space} 78 | } 79 | \expandafter\scantokens\expandafter{% 80 | \expandafter\catcode\expandafter`\CPT@escape@hat@hat@E=0} 81 | \expandafter\scantokens\expandafter{% 82 | \expandafter\catcode\expandafter`\CPT@hat@hat@E@hat@hat@L=11} 83 | \expandafter\scantokens\expandafter{% 84 | \expandafter\def\CPT@hat@hat@E@hat@hat@L{}} 85 | \newcommand\ReadVerbatimUntil[2][]{% 86 | \def\CPT@commandatend{#2}% 87 | \begingroup #1% 88 | \makeallother% 89 | \CPT@setup} 90 | \WithSuffix\newcommand\ReadVerbatimUntil*[2][]{% 91 | \def\CPT@commandatend{#2}% 92 | \begingroup #1% 93 | \makeallother% 94 | \CPT@starsetup} 95 | \newcommand{\CPT@def}[2]{\expandafter\def\expandafter#1% 96 | \expandafter##\expandafter1#2} 97 | \newcommand{\CPT@setup}[1]{% 98 | \def\CPT@delimiter{#1}% 99 | \CPT@def\CPT@readPreText\CPT@delimiter{% 100 | \def\CPT@preText{##1}\CPT@readPostText}% 101 | \CPT@def\CPT@readPostText\CPT@delimiter{% 102 | \def\CPT@postText{##1}\CPT@readBegin}% 103 | \CPT@def\CPT@readBegin\CPT@delimiter{% 104 | \def\CPT@begin{##1}\CPT@readEnd}% 105 | \CPT@def\CPT@readEnd\CPT@delimiter{% 106 | \def\CPT@end{##1}\CPT@readContent}% 107 | \CPT@readPreText% 108 | } 109 | \newcommand{\CPT@starsetup}[1]{\CPT@setup#1#1#1} 110 | \newcounter{CPT@numB} 111 | \newcommand{\CPT@store}[1]{\edef\CPT@storage{\CPT@storage#1}} 112 | \newcommand{\CPT@readContent}{% 113 | \CPT@def\CPT@gobbleOneB\CPT@begin##2{% 114 | \ifx\CPT@qend##2\CPT@store{##1}\addtocounter{CPT@numB}{-1}% 115 | \else\CPT@store{##1\CPT@begin}\stepcounter{CPT@numB}% 116 | \expandafter\CPT@gobbleOneB\expandafter##2\fi}% 117 | % 118 | \CPT@def\CPT@gobbleUntilE\CPT@end{% 119 | \edef\CPT@tempi{##1\CPT@begin}% 120 | \expandafter\CPT@gobbleOneB\CPT@tempi\CPT@qend% 121 | \ifthenelse{\value{CPT@numB}<0}{% 122 | \CPT@store{\CPT@postText}% 123 | \CPT@Write{\CPT@storage}\endgroup% 124 | \CPT@commandatend% 125 | }{% 126 | \CPT@store{\CPT@end}\CPT@gobbleUntilE% 127 | }% 128 | }% 129 | \setcounter{CPT@numB}{0}% 130 | \def\CPT@storage{\CPT@preText}% 131 | \CPT@gobbleUntilE% 132 | } 133 | \outer\long\def\cprotect{\icprotect} 134 | \newtoks\CPT@commandatend@toks 135 | \newcommand{\icprotect}[2][om]{% 136 | \def\CPT@argsig{#1}% 137 | \def\CPT@cs{#2}% 138 | \CPT@commandatend@toks{#2}% 139 | \def\CPT@commandatend{\CPT@read@args}% used by RVU. 140 | \CPT@commandatend% 141 | } 142 | \def\CPT@argsig@pop{% 143 | \edef\CPT@argsig{\expandafter\@gobble\CPT@argsig}% 144 | } 145 | %\newcommand\CPT@read@args{\CPT@read@m} 146 | \newcommand\CPT@read@args{% 147 | \ifx\CPT@argsig\empty 148 | \expandafter\the\expandafter\CPT@commandatend@toks 149 | \else 150 | \expandafter\expandafter\expandafter\CPT@read@one 151 | \expandafter\CPT@argsig\expandafter\CPT@qend% 152 | \fi 153 | } 154 | \def\CPT@read@one#1#2\CPT@qend{% 155 | \def\CPT@argsig{#2}% 156 | \def\CPT@tempii{\csname CPT@read@#1\endcsname}% To make the \afterassignment simpler. 157 | \afterassignment\CPT@tempii\let\CPT@next=% 158 | } 159 | \newcommand\CPT@read@m{% 160 | \ifx\CPT@next\bgroup% 161 | \expandafter\CPT@read@mbeg% 162 | \else% 163 | \expandafter\CPT@read@mone% 164 | \fi% 165 | } 166 | \def\CPT@read@mone{\CPT@cs\CPT@next} 167 | \begingroup 168 | \catcode`\{=12 \catcode`\}=12 169 | \catcode`\(=1 \catcode`\)=2 170 | \gdef\CPT@other@bgroup({) 171 | \gdef\CPT@other@egroup(}) 172 | \endgroup 173 | \def\CPT@read@mbeg{% 174 | \stepcounter{CPT@WriteCount}% 175 | \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}% 176 | \expandafter\expandafter\expandafter\CPT@commandatend@toks 177 | \expandafter\expandafter\expandafter{% 178 | \expandafter\the 179 | \expandafter\CPT@commandatend@toks 180 | % Input a file: 181 | \expandafter{% 182 | \expandafter\protect 183 | \expandafter\input 184 | \CPT@filename 185 | \relax 186 | }% 187 | % % Using \scantokens: requires '%' active. 188 | % \expandafter{% 189 | % \csname \string\CPT@\CPT@filename\endcsname 190 | % \expandafter\protect 191 | % \expandafter\csname CPT@\CPT@filename\endcsname 192 | % }% 193 | }% 194 | %\showthe\CPT@commandatend@toks% 195 | \begingroup% 196 | \makeallother% 197 | \def\CPT@preText{}% 198 | \let\CPT@postText\CPT@hat@hat@E@hat@hat@L% 199 | \let\CPT@begin\CPT@other@bgroup% 200 | \let\CPT@end\CPT@other@egroup% 201 | \CPT@readContent% 202 | }% 203 | \def\CPT@read@o{\CPT@read@d[]} 204 | \def\CPT@read@d#1#2{% 205 | \if\noexpand\CPT@next#1% 206 | \expandafter\CPT@read@d@beg% 207 | \else% 208 | \expandafter\CPT@read@d@none% 209 | \fi% 210 | {#1}{#2}% 211 | } 212 | \def\CPT@read@d@none#1#2{% 213 | \CPT@read@args\CPT@next% 214 | } 215 | \def\CPT@read@d@beg#1#2{% 216 | \stepcounter{CPT@WriteCount}% 217 | \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}% 218 | \expandafter\expandafter\expandafter\CPT@commandatend@toks% 219 | \expandafter\expandafter\expandafter{% 220 | \expandafter\the% 221 | \expandafter\CPT@commandatend@toks% 222 | \expandafter #1% 223 | \expandafter\protect% 224 | \expandafter\input% 225 | \CPT@filename% 226 | \relax% 227 | #2% 228 | }% 229 | \begingroup% 230 | \makeallother% 231 | \def\CPT@preText{}% 232 | \let\CPT@postText\CPT@hat@hat@E@hat@hat@L% 233 | \def\CPT@begin{#1}% 234 | \def\CPT@end{#2}% 235 | \CPT@readContent% 236 | }% 237 | \newcommand{\cMakeRobust}[1]{% 238 | \def\CPT@cs@name{\expandafter\@gobble\string#1}% 239 | \expandafter\let\csname CPT@old@\CPT@cs@name\endcsname #1% 240 | \expandafter\outer\expandafter\def\csname\CPT@cs@name\endcsname{% 241 | \expandafter\icprotect\csname CPT@old@\CPT@cs@name\endcsname}% 242 | } 243 | \newcommand{\CPTbegin}[1]{% 244 | \stepcounter{CPT@WriteCount}% 245 | \edef\CPT@filename{\jobname-\arabic{CPT@WriteCount}.cpt}% 246 | \edef\CPT@commandatend{% 247 | \noexpand\begin\noexpand{\noexpand#1\noexpand}% 248 | \noexpand\expandafter\noexpand\protect% 249 | \noexpand\expandafter\noexpand\input \CPT@filename\relax% 250 | \noexpand\end\noexpand{\noexpand#1\noexpand}% 251 | }% 252 | \begingroup% 253 | \CPT@env@setup{#1}% 254 | \makeallother% 255 | \CPT@readContent% 256 | } 257 | \newcommand{\CPT@otherify}[1]{% 258 | \expandafter\expandafter\expandafter\@gobble 259 | \expandafter\string\csname #1\endcsname 260 | } 261 | \newcommand{\CPT@env@setup}[1]{% 262 | \def\CPT@temp{#1}% 263 | \edef\CPT@temp{\CPT@otherify{#1}}% 264 | \edef\CPT@temp{\expandafter\strip@prefix\meaning\CPT@temp}% 265 | \expandafter\CPT@env@setup@\expandafter{\CPT@temp}% 266 | } 267 | \def\CPT@env@setup@#1{% 268 | \let\CPT@preText\CPT@hat@hat@E@hat@hat@L% 269 | \let\CPT@postText\CPT@hat@hat@E@hat@hat@L% 270 | \edef\CPT@begin{\string\begin\string{#1\string}}% 271 | \edef\CPT@end{\string\end\string{#1\string}}% 272 | } 273 | \def\cprotEnv\begin{\CPTbegin} 274 | %% 275 | %% Copyright (C) 2010-2011 by Bruno Le Floch 276 | %% 277 | %% This work may be distributed and/or modified under the 278 | %% conditions of the LaTeX Project Public License (LPPL), either 279 | %% version 1.3c of this license or (at your option) any later 280 | %% version. The latest version of this license is in the file: 281 | %% 282 | %% http://www.latex-project.org/lppl.txt 283 | %% 284 | %% This work is "maintained" (as per LPPL maintenance status) by 285 | %% Bruno Le Floch. 286 | %% 287 | %% This work consists of the file cprotect.dtx 288 | %% and the derived files cprotect.ins, 289 | %% cprotect.pdf and 290 | %% cprotect.sty. 291 | %% 292 | %% 293 | %% End of file `cprotect.sty'. 294 | -------------------------------------------------------------------------------- /figs/bro-logo-small.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeek/cheat-sheet/9ab06d802b1f321a4862ce417d012d5701ba7ba1/figs/bro-logo-small.pdf -------------------------------------------------------------------------------- /figs/by-nc-sa.pdf: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeek/cheat-sheet/9ab06d802b1f321a4862ce417d012d5701ba7ba1/figs/by-nc-sa.pdf -------------------------------------------------------------------------------- /figs/shot-bif.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeek/cheat-sheet/9ab06d802b1f321a4862ce417d012d5701ba7ba1/figs/shot-bif.png -------------------------------------------------------------------------------- /figs/shot-main.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/zeek/cheat-sheet/9ab06d802b1f321a4862ce417d012d5701ba7ba1/figs/shot-main.png --------------------------------------------------------------------------------