Mirror/zeek
1
0
Fork 0
mirror of https://github.com/zeek/zeek.git synced 2025-10-06 08:38:20 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 2

Improvements to file analysis docs

Browse source 
Fixed reference to wrong field name.
Added documentation of a function arg.
Added a couple references to other parts of the documentation.
Explained how not specifying extraction filename results in automatic
filename generation.
Several other minor clarifications.
This commit is contained in:
Daniel Thayer 2013-10-11 16:31:53 -05:00
parent 60b2c5f1fe
commit b5af589246
3 changed files with 24 additions and 17 deletions
Download patch file Download diff file Expand all files Collapse all files

7
scripts/base/files/extract/main.bro
View file

@ -12,14 +12,17 @@ export {
const default_limit = 0 &redef;
redef record Files::Info += {
## Local filenames of extracted file.
## Local filename of extracted file.
extracted: string &optional &log;
};
redef record Files::AnalyzerArgs += {
## The local filename to which to write an extracted file.
## This field is used in the core by the extraction plugin
## to know where to write the file to. It's also optional.
## to know where to write the file to. If not specified, then
## a filename in the format "extract-<source>-<id>" is
## automatically assigned (using the *source* and *id*
## fields of :bro:see:`fa_file`).
extract_filename: string &optional;
## The maximum allowed file size in bytes of *extract_filename*.
## Once reached, a :bro:see:`file_extraction_limit` event is

28
scripts/base/frameworks/files/main.bro
View file

@ -14,10 +14,11 @@ export {
LOG
};
## A structure which represents a desired type of file analysis.
## A structure which parameterizes a type of file analysis.
type AnalyzerArgs: record {
## An event which will be generated for all new file contents,
## chunk-wise. Used when *tag* is
## chunk-wise. Used when *tag* (in the
## :bro:see:`Files::add_analyzer` function) is
## :bro:see:`Files::ANALYZER_DATA_EVENT`.
chunk_event: event(f: fa_file, data: string, off: count) &optional;
@ -47,7 +48,7 @@ export {
## the data traveled to.
rx_hosts: set[addr] &log;
## Connection UIDS over which the file was transferred.
## Connection UIDs over which the file was transferred.
conn_uids: set[string] &log;
## An identification of the source of the file data. E.g. it
@ -64,9 +65,10 @@ export {
## A set of analysis types done during the file analysis.
analyzers: set[string] &log;
## A mime type provided by libmagic against the *bof_buffer*, or
## in the cases where no buffering of the beginning of file occurs,
## an initial guess of the mime type based on the first data seen.
## A mime type provided by libmagic against the *bof_buffer*
## field of :bro:see:`fa_file`, or in the cases where no
## buffering of the beginning of file occurs, an initial
## guess of the mime type based on the first data seen.
mime_type: string &log &optional;
## A filename for the file if one is available from the source
@ -132,7 +134,7 @@ export {
## t: the amount of time the file can remain inactive before discarding.
##
## Returns: true if the timeout interval was set, or false if analysis
## for the *id* isn't currently active.
## for the file isn't currently active.
global set_timeout_interval: function(f: fa_file, t: interval): bool;
## Adds an analyzer to the analysis of a given file.
@ -144,7 +146,7 @@ export {
## args: any parameters the analyzer takes.
##
## Returns: true if the analyzer will be added, or false if analysis
## for the *id* isn't currently active or the *args*
## for the file isn't currently active or the *args*
## were invalid for the analyzer type.
global add_analyzer: function(f: fa_file,
tag: Files::Tag,
@ -154,10 +156,12 @@ export {
##
## f: the file.
##
## tag: the analyzer type.
##
## args: the analyzer (type and args) to remove.
##
## Returns: true if the analyzer will be removed, or false if analysis
## for the *id* isn't currently active.
## for the file isn't currently active.
global remove_analyzer: function(f: fa_file,
tag: Files::Tag,
args: AnalyzerArgs &default=AnalyzerArgs()): bool;
@ -167,12 +171,12 @@ export {
## f: the file.
##
## Returns: true if analysis for the given file will be ignored for the
## rest of its contents, or false if analysis for the *id*
## rest of its contents, or false if analysis for the file
## isn't currently active.
global stop: function(f: fa_file): bool;
## Translates a file analyzer enum value to a string with the analyzer's
## name.
## Translates a file analyzer enum value to a string with the
## analyzer's name.
##
## tag: The analyzer tag.
##

6
src/file_analysis/analyzer/extract/events.bif
View file

@ -1,6 +1,6 @@
## This event is generated when a file extraction analyzer is about
## to exceed the maximum permitted file size allowed by
## *extract_size_limit* field of :bro:see:`Files::AnalyzerArgs`.
## to exceed the maximum permitted file size allowed by the
## *extract_limit* field of :bro:see:`Files::AnalyzerArgs`.
## The analyzer is automatically removed from file *f*.
##
## f: The file.
@ -13,7 +13,7 @@
##
## offset: The offset at which a file chunk is about to be written.
##
## len:: The length of the file chunk about to be written.
## len: The length of the file chunk about to be written.
##
## .. bro:see:: Files::add_analyzer Files::ANALYZER_EXTRACT
event file_extraction_limit%(f: fa_file, args: any, limit: count, offset: count, len: count%);