Merge pull request #246 from draios/dev

Merging for 0.7.0

CHANGELOG.md

@@ -2,6 +2,49 @@
 
 This file documents all notable changes to Falco. The release numbering uses [semantic versioning](http://semver.org).
 
+## v0.7.0
+
+Released 2016-05-30
+
+### Major Changes
+
+* Update the priorities of falco rules to use a wider range of priorities rather than just ERROR/WARNING. More info on the use of priorities in the ruleset can be found [here](https://github.com/draios/falco/wiki/Falco-Rules#rule-priorities). [[#244](https://github.com/draios/falco/pull/244)]
+
+### Minor Changes
+
+None.
+
+### Bug Fixes
+
+* Fix typos in various markdown files. Thanks @sublimino! [[#241](https://github.com/draios/falco/pull/241)]
+
+### Rule Changes
+
+* Add gitlab-mon as a gitlab binary, which allows it to run shells, etc. Thanks @dkerwin! [[#237](https://github.com/draios/falco/pull/237)]
+* A new rule Terminal shell in container" that looks for shells spawned in a container with an attached terminal. [[#242](https://github.com/draios/falco/pull/242)]
+* Fix some FPs related to the sysdig monitor agent. [[#243](https://github.com/draios/falco/pull/243)]
+* Fix some FPs related to stating containers combined with missed events [[#243](https://github.com/draios/falco/pull/243)]
+
+## v0.6.1
+
+Released 2016-05-15
+
+### Major Changes
+
+None
+
+### Minor Changes
+
+* Small changes to token bucket used to throttle falco events [[#234](https://github.com/draios/falco/pull/234)] [[#235](https://github.com/draios/falco/pull/235)] [[#236](https://github.com/draios/falco/pull/236)] [[#238](https://github.com/draios/falco/pull/238)]
+
+### Bug Fixes
+
+* Update the falco driver to work with kernel 4.11 [[#829](https://github.com/draios/sysdig/pull/829)]
+
+### Rule Changes
+
+* Don't allow apache2 to spawn shells in containers [[#231](https://github.com/draios/falco/issues/231)] [[#232](https://github.com/draios/falco/pull/232)]
+
 ## v0.6.0
 
 Released 2016-03-29

README.md

@@ -2,7 +2,7 @@
 
 #### Latest release
 
-**v0.6.0**
+**v0.7.0**
 Read the [change log](https://github.com/draios/falco/blob/dev/CHANGELOG.md)
 
 Dev Branch: [![Build Status](https://travis-ci.org/draios/falco.svg?branch=dev)](https://travis-ci.org/draios/falco)<br />
@@ -29,13 +29,13 @@ One of the questions we often get when we talk about Sysdig Falco is “How does
 
 Documentation
 ---
-[Visit the wiki] (https://github.com/draios/falco/wiki) for full documentation on falco.
+[Visit the wiki](https://github.com/draios/falco/wiki) for full documentation on falco.
 
 Join the Community
 ---
-* Contact the [official mailing list] (https://groups.google.com/forum/#!forum/falco) for support and to talk with other users.
-* Follow us on [Twitter] (https://twitter.com/sysdig) for general falco and sysdig news.
-* This is our [blog] (https://sysdig.com/blog/), where you can find the latest [falco](https://sysdig.com/blog/tag/falco/) posts.
+* Contact the [official mailing list](https://groups.google.com/forum/#!forum/falco) for support and to talk with other users.
+* Follow us on [Twitter](https://twitter.com/sysdig) for general falco and sysdig news.
+* This is our [blog](https://sysdig.com/blog/), where you can find the latest [falco](https://sysdig.com/blog/tag/falco/) posts.
 * Join our [Public Slack](https://sysdig.slack.com) channel for sysdig and falco announcements and discussions.
 
 License Terms

rules/falco_rules.yaml

@@ -114,7 +114,7 @@
   items: [mysqld]
 
 - list: gitlab_binaries
-  items: [gitlab-shell, git]
+  items: [gitlab-shell, gitlab-mon, git]
 
 - macro: server_procs
   condition: proc.name in (http_server_binaries, db_server_binaries, docker_binaries, sshd)
@@ -241,6 +241,9 @@
 - macro: parent_linux_image_upgrade_script
   condition: proc.pname startswith linux-image-
 
+- macro: java_running_sdjagent
+  condition: proc.name=java and proc.cmdline contains sdjagent.jar
+
 ###############
 # General Rules
 ###############
@@ -249,7 +252,7 @@
   desc: an attempt to write to any file below a set of binary directories
   condition: bin_dir and evt.dir = < and open_write and not package_mgmt_procs
   output: "File below a known binary directory opened for writing (user=%user.name command=%proc.cmdline file=%fd.name)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem]
 
 - macro: write_etc_common
@@ -269,7 +272,7 @@
   desc: an attempt to write to any file below /etc, not in a pipe installer session
   condition: write_etc_common and not proc.sname=fbash
   output: "File below /etc opened for writing (user=%user.name command=%proc.cmdline file=%fd.name)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem]
 
 # Within a fbash session, the severity is lowered to INFO
@@ -310,28 +313,28 @@
   desc: an attempt to write to the rpm database by any non-rpm related program
   condition: fd.name startswith /var/lib/rpm and open_write and not proc.name in (dnf,rpm,rpmkey,yum) and not ansible_running_python
   output: "Rpm database opened for writing by a non-rpm program (command=%proc.cmdline file=%fd.name)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem, software_mgmt]
 
 - rule: DB program spawned process
   desc: a database-server related program spawned a new process other than itself. This shouldn\'t occur and is a follow on from some SQL injection attacks.
   condition: proc.pname in (db_server_binaries) and spawned_process and not proc.name in (db_server_binaries)
   output: "Database-related program spawned process other than itself (user=%user.name program=%proc.cmdline parent=%proc.pname)"
-  priority: WARNING
+  priority: NOTICE
   tags: [process, database]
 
 - rule: Modify binary dirs
   desc: an attempt to modify any file below a set of binary directories.
   condition: bin_dir_rename and modify and not package_mgmt_procs
   output: "File below known binary directory renamed/removed (user=%user.name command=%proc.cmdline operation=%evt.type file=%fd.name %evt.args)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem]
 
 - rule: Mkdir binary dirs
   desc: an attempt to create a directory below a set of binary directories.
   condition: mkdir and bin_dir_mkdir and not package_mgmt_procs
   output: "Directory below known binary directory created (user=%user.name command=%proc.cmdline directory=%evt.arg.path)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem]
 
 # Don't load shared objects coming from unexpected places
@@ -355,9 +358,11 @@
   condition: >
     evt.type = setns
     and not proc.name in (docker_binaries, k8s_binaries, lxd_binaries, sysdigcloud_binaries, sysdig, nsenter)
+    and not proc.name startswith "runc:"
     and not proc.pname in (sysdigcloud_binaries)
+    and not java_running_sdjagent
   output: "Namespace change (setns) by unexpected program (user=%user.name command=%proc.cmdline parent=%proc.pname %container.info)"
-  priority: WARNING
+  priority: NOTICE
   tags: [process]
 
 - list: known_shell_spawn_binaries
@@ -385,7 +390,7 @@
     and not parent_python_running_denyhosts
     and not parent_linux_image_upgrade_script
   output: "Shell spawned by untrusted binary (user=%user.name shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline pcmdline=%proc.pcmdline)"
-  priority: WARNING
+  priority: DEBUG
   tags: [host, shell]
 
 - macro: trusted_containers
@@ -401,7 +406,7 @@
   desc: Any open by a privileged container. Exceptions are made for known trusted images.
   condition: (open_read or open_write) and container and container.privileged=true and not trusted_containers
   output: File opened for read/write by privileged container (user=%user.name command=%proc.cmdline %container.info file=%fd.name)
-  priority: WARNING
+  priority: INFO
   tags: [container, cis]
 
 - macro: sensitive_mount
@@ -411,7 +416,7 @@
   desc: Any open by a container that has a mount from a sensitive host directory (i.e. /proc). Exceptions are made for known trusted images.
   condition: (open_read or open_write) and container and sensitive_mount and not trusted_containers
   output: File opened for read/write by container mounting sensitive directory (user=%user.name command=%proc.cmdline %container.info file=%fd.name)
-  priority: WARNING
+  priority: INFO
   tags: [container, cis]
 
 # Anything run interactively by root
@@ -423,9 +428,18 @@
   desc: an attempt to run interactive commands by a system (i.e. non-login) user
   condition: spawned_process and system_users and interactive
   output: "System user ran an interactive command (user=%user.name command=%proc.cmdline)"
-  priority: WARNING
+  priority: INFO
   tags: [users]
 
+- rule: Terminal shell in container
+  desc: A shell was spawned by a program in a container with an attached terminal.
+  condition: >
+    spawned_process and container
+    and shell_procs and proc.tty != 0
+  output: "A shell was spawned in a container with an attached terminal (user=%user.name %container.info shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline terminal=%proc.tty)"
+  priority: NOTICE
+  tags: [container, shell]
+
 - rule: Run shell in container
   desc: a shell was spawned by a non-shell program in a container. Container entrypoints are excluded.
   condition: >
@@ -433,10 +447,10 @@
     and shell_procs
     and proc.pname exists
     and not proc.pname in (shell_binaries, docker_binaries, k8s_binaries, lxd_binaries, aide_wrapper_binaries, nids_binaries,
-                           monitoring_binaries, gitlab_binaries, initdb, pg_ctl, awk, apache2, falco, cron, erl_child_setup)
+                           monitoring_binaries, gitlab_binaries, initdb, pg_ctl, awk, falco, cron, erl_child_setup)
     and not trusted_containers
   output: "Shell spawned in a container other than entrypoint (user=%user.name %container.info shell=%proc.name parent=%proc.pname cmdline=%proc.cmdline)"
-  priority: WARNING
+  priority: NOTICE
   tags: [container, shell]
 
 # sockfamily ip is to exclude certain processes (like 'groups') that communicate on unix-domain sockets
@@ -444,7 +458,7 @@
   desc: any network activity performed by system binaries that are not expected to send or receive any network traffic
   condition: (fd.sockfamily = ip and system_procs) and (inbound or outbound)
   output: "Known system binary sent/received network traffic (user=%user.name command=%proc.cmdline connection=%fd.name)"
-  priority: WARNING
+  priority: NOTICE
   tags: [network]
 
 # With the current restriction on system calls handled by falco
@@ -461,14 +475,14 @@
   desc: an attempt to change users by calling setuid. sudo/su are excluded. user "root" is also excluded, as setuid calls typically involve dropping privileges.
   condition: evt.type=setuid and evt.dir=> and not user.name=root and not proc.name in (userexec_binaries, mail_binaries, sshd, dbus-daemon-lau, ping, ping6, critical-stack-)
   output: "Unexpected setuid call by non-sudo, non-root program (user=%user.name parent=%proc.pname command=%proc.cmdline uid=%evt.arg.uid)"
-  priority: WARNING
+  priority: NOTICE
   tags: [users]
 
 - rule: User mgmt binaries
   desc: activity by any programs that can manage users, passwords, or permissions. sudo and su are excluded. Activity in containers is also excluded--some containers create custom users on top of a base linux distribution at startup.
   condition: spawned_process and proc.name in (user_mgmt_binaries) and not proc.name in (su, sudo) and not container and not proc.pname in (cron_binaries, systemd, run-parts)
   output: "User management binary command run outside of container (user=%user.name command=%proc.cmdline parent=%proc.pname)"
-  priority: WARNING
+  priority: NOTICE
   tags: [host, users]
 
 - list: allowed_dev_files
@@ -484,7 +498,7 @@
     and not fd.name in (allowed_dev_files)
     and not fd.name startswith /dev/tty
   output: "File created below /dev by untrusted program (user=%user.name command=%proc.cmdline file=%fd.name)"
-  priority: WARNING
+  priority: ERROR
   tags: [filesystem]
 
 # fbash is a small shell script that runs bash, and is suitable for use in curl <curl> | fbash installers.
@@ -492,21 +506,21 @@
   desc: an attempt by a program in a pipe installer session to start listening for network connections
   condition: evt.type=listen and proc.sname=fbash
   output: "Unexpected listen call by a process in a fbash session (command=%proc.cmdline)"
-  priority: WARNING
+  priority: NOTICE
   tags: [network]
 
 - rule: Installer bash starts session
   desc: an attempt by a program in a pipe installer session to start a new session
   condition: evt.type=setsid and proc.sname=fbash
   output: "Unexpected setsid call by a process in fbash session (command=%proc.cmdline)"
-  priority: WARNING
+  priority: NOTICE
   tags: [process]
 
 - rule: Installer bash non https connection
   desc: an attempt by a program in a pipe installer session to make an outgoing connection on a non-http(s) port
   condition: proc.sname=fbash and outbound and not fd.sport in (80, 443, 53)
   output: "Outbound connection on non-http(s) port by a process in a fbash session (command=%proc.cmdline connection=%fd.name)"
-  priority: WARNING
+  priority: NOTICE
   tags: [network]
 
 # It'd be nice if we could warn when processes in a fbash session try

test/falco_traces.yaml.in

@@ -0,0 +1,203 @@
+has_json_output: !mux
+  yes:
+    json_output: True
+  no:
+    json_output: False
+
+traces: !mux
+  change-thread-namespace:
+    trace_file: traces-positive/change-thread-namespace.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Change thread namespace": 2
+
+  container-privileged:
+    trace_file: traces-positive/container-privileged.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "File Open by Privileged Container": 19
+
+  container-sensitive-mount:
+    trace_file: traces-positive/container-sensitive-mount.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "Sensitive Mount by Container": 19
+
+  create-files-below-dev:
+    trace_file: traces-positive/create-files-below-dev.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Create files below dev": 1
+
+  db-program-spawned-process:
+    trace_file: traces-positive/db-program-spawned-process.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "DB program spawned process": 1
+
+  falco-event-generator:
+    trace_file: traces-positive/falco-event-generator.scap
+    detect: True
+    detect_level: [ERROR, WARNING, INFO, NOTICE]
+    detect_counts:
+      - "Write below binary dir": 1
+      - "Read sensitive file untrusted": 3
+      - "Run shell in container": 1
+      - "Write below rpm database": 1
+      - "Write below etc": 1
+      - "System procs network activity": 1
+      - "Mkdir binary dirs": 1
+      - "System user interactive": 1
+      - "DB program spawned process": 1
+      - "Non sudo setuid": 1
+      - "Create files below dev": 1
+      - "Modify binary dirs": 2
+      - "Change thread namespace": 2
+
+  installer-fbash-manages-service:
+    trace_file: traces-info/installer-fbash-manages-service.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "Installer bash manages service": 4
+
+  installer-bash-non-https-connection:
+    trace_file: traces-positive/installer-bash-non-https-connection.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Installer bash non https connection": 1
+
+  installer-fbash-runs-pkgmgmt:
+    trace_file: traces-info/installer-fbash-runs-pkgmgmt.scap
+    detect: True
+    detect_level: [NOTICE, INFO]
+    detect_counts:
+      - "Installer bash runs pkgmgmt program": 4
+      - "Installer bash non https connection": 4
+
+  installer-bash-starts-network-server:
+    trace_file: traces-positive/installer-bash-starts-network-server.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Installer bash starts network server": 2
+      - "Installer bash non https connection": 3
+
+  installer-bash-starts-session:
+    trace_file: traces-positive/installer-bash-starts-session.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Installer bash starts session": 1
+      - "Installer bash non https connection": 3
+
+  mkdir-binary-dirs:
+    trace_file: traces-positive/mkdir-binary-dirs.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Mkdir binary dirs": 1
+
+  modify-binary-dirs:
+    trace_file: traces-positive/modify-binary-dirs.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Modify binary dirs": 1
+
+  modify-package-repo-list-installer:
+    trace_file: traces-info/modify-package-repo-list-installer.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "Write below etc in installer": 1
+
+  non-sudo-setuid:
+    trace_file: traces-positive/non-sudo-setuid.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Non sudo setuid": 1
+
+  read-sensitive-file-after-startup:
+    trace_file: traces-positive/read-sensitive-file-after-startup.scap
+    detect: True
+    detect_level: WARNING
+    detect_counts:
+      - "Read sensitive file untrusted": 1
+
+  read-sensitive-file-untrusted:
+    trace_file: traces-positive/read-sensitive-file-untrusted.scap
+    detect: True
+    detect_level: WARNING
+    detect_counts:
+      - "Read sensitive file untrusted": 1
+
+  run-shell-untrusted:
+    trace_file: traces-positive/run-shell-untrusted.scap
+    detect: True
+    detect_level: DEBUG
+    detect_counts:
+      - "Run shell untrusted": 1
+
+  shell-in-container:
+    trace_file: traces-positive/shell-in-container.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "Run shell in container": 1
+
+  system-binaries-network-activity:
+    trace_file: traces-positive/system-binaries-network-activity.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "System procs network activity": 1
+
+  system-user-interactive:
+    trace_file: traces-positive/system-user-interactive.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "System user interactive": 1
+
+  user-mgmt-binaries:
+    trace_file: traces-positive/user-mgmt-binaries.scap
+    detect: True
+    detect_level: NOTICE
+    detect_counts:
+      - "User mgmt binaries": 1
+
+  write-binary-dir:
+    trace_file: traces-positive/write-binary-dir.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Write below binary dir": 4
+
+  write-etc:
+    trace_file: traces-positive/write-etc.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Write below etc": 1
+
+  write-etc-installer:
+    trace_file: traces-info/write-etc-installer.scap
+    detect: True
+    detect_level: INFO
+    detect_counts:
+      - "Write below etc in installer": 1
+
+  write-rpm-database:
+    trace_file: traces-positive/write-rpm-database.scap
+    detect: True
+    detect_level: ERROR
+    detect_counts:
+      - "Write below rpm database": 1

test/run_regression_tests.sh

@@ -2,7 +2,6 @@
 
 SCRIPT=$(readlink -f $0)
 SCRIPTDIR=$(dirname $SCRIPT)
-MULT_FILE=$SCRIPTDIR/falco_tests.yaml
 BRANCH=$1
 
 function download_trace_files() {
@@ -19,56 +18,59 @@ function prepare_multiplex_fileset() {
 
     dir=$1
     detect=$2
-    detect_level=$3
-    json_output=$4
 
     for trace in $SCRIPTDIR/$dir/*.scap ; do
 	[ -e "$trace" ] || continue
 	NAME=`basename $trace .scap`
-	cat << EOF >> $MULT_FILE
-  $NAME-detect-$detect-json-$json_output:
+
+	# falco_traces.yaml might already have an entry for this trace
+	# file, with specific detection levels and counts. If so, skip
+	# it. Otherwise, add a generic entry showing whether or not to
+	# detect anything.
+	grep -q "$NAME:" $SCRIPTDIR/falco_traces.yaml && continue
+
+	cat << EOF >> $SCRIPTDIR/falco_traces.yaml
+  $NAME:
     detect: $detect
-    detect_level: $detect_level
+    detect_level: WARNING
     trace_file: $trace
-    json_output: $json_output
 EOF
     done
 }
 
 function prepare_multiplex_file() {
-    cp $SCRIPTDIR/falco_tests.yaml.in $MULT_FILE
+    cp $SCRIPTDIR/falco_traces.yaml.in $SCRIPTDIR/falco_traces.yaml
 
-    prepare_multiplex_fileset traces-positive True WARNING False
-    prepare_multiplex_fileset traces-negative False WARNING True
-    prepare_multiplex_fileset traces-info True INFO False
+    prepare_multiplex_fileset traces-positive True
+    prepare_multiplex_fileset traces-negative False
+    prepare_multiplex_fileset traces-info True
 
-    prepare_multiplex_fileset traces-positive True WARNING True
-    prepare_multiplex_fileset traces-info True INFO True
-
-    echo "Contents of $MULT_FILE:"
-    cat $MULT_FILE
+    echo "Contents of $SCRIPTDIR/falco_traces.yaml:"
+    cat $SCRIPTDIR/falco_traces.yaml
 }
 
-function run_tests() {
-    rm -rf /tmp/falco_outputs
-    mkdir /tmp/falco_outputs
-    CMD="avocado run --multiplex $MULT_FILE --job-results-dir $SCRIPTDIR/job-results -- $SCRIPTDIR/falco_test.py"
-    echo "Running: $CMD"
-    $CMD
-    TEST_RC=$?
-}
-
-
 function print_test_failure_details() {
     echo "Showing full job logs for any tests that failed:"
     jq '.tests[] | select(.status != "PASS") | .logfile' $SCRIPTDIR/job-results/latest/results.json  | xargs cat
 }
 
+function run_tests() {
+    rm -rf /tmp/falco_outputs
+    mkdir /tmp/falco_outputs
+    TEST_RC=0
+    for mult in $SCRIPTDIR/falco_traces.yaml $SCRIPTDIR/falco_tests.yaml; do
+	CMD="avocado run --multiplex $mult --job-results-dir $SCRIPTDIR/job-results -- $SCRIPTDIR/falco_test.py"
+	echo "Running: $CMD"
+	$CMD
+	RC=$?
+	TEST_RC=$((TEST_RC+$RC))
+	if [ $RC -ne 0 ]; then
+	    print_test_failure_details
+	fi
+    done
+}
+
 download_trace_files
 prepare_multiplex_file
 run_tests
-if [ $TEST_RC -ne 0 ]; then
-   print_test_failure_details
-fi
-
 exit $TEST_RC

userspace/engine/token_bucket.cpp

@@ -31,20 +31,30 @@ token_bucket::~token_bucket()
 {
 }
 
-void token_bucket::init(uint32_t rate, uint32_t max_tokens)
+void token_bucket::init(double rate, double max_tokens, uint64_t now)
 {
 	m_rate = rate;
 	m_max_tokens = max_tokens;
 	m_tokens = max_tokens;
-	m_last_seen = sinsp_utils::get_current_time_ns();
+
+	if(now == 0)
+	{
+		now = sinsp_utils::get_current_time_ns();
+	}
+
+	m_last_seen = now;
 }
 
 bool token_bucket::claim()
 {
-	// Determine the number of tokens gained. Delta between
-	// last_seen and now, divided by the rate.
 	uint64_t now = sinsp_utils::get_current_time_ns();
-	uint64_t tokens_gained = (now - m_last_seen) / (m_rate * 1000000000);
+
+	return claim(1, now);
+}
+
+bool token_bucket::claim(double tokens, uint64_t now)
+{
+	double tokens_gained = m_rate * ((now - m_last_seen) / (1000000000.0));
 	m_last_seen = now;
 
 	m_tokens += tokens_gained;
@@ -58,14 +68,24 @@ bool token_bucket::claim()
 	}
 
 	//
-	// If tokens is < 1, can't claim.
+	// If m_tokens is < tokens, can't claim.
 	//
-	if(m_tokens < 1)
+	if(m_tokens < tokens)
 	{
 		return false;
 	}
 
-	m_tokens--;
+	m_tokens -= tokens;
 
 	return true;
 }
+
+double token_bucket::get_tokens()
+{
+	return m_tokens;
+}
+
+uint64_t token_bucket::get_last_seen()
+{
+	return m_last_seen;
+}

userspace/engine/token_bucket.h

@@ -31,30 +31,42 @@ public:
 	//
 	// Initialize the token bucket and start accumulating tokens
 	//
-	void init(uint32_t rate, uint32_t max_tokens);
+	void init(double rate, double max_tokens, uint64_t now = 0);
 
 	//
-	// Returns true if a token can be claimed. Also updates
-	// internal metrics.
+	// Try to claim tokens tokens from the token bucket, using a
+	// timestamp of now. Returns true if the tokens could be
+	// claimed. Also updates internal metrics.
 	//
+	bool claim(double tokens, uint64_t now);
+
+	// Simpler version of claim that claims a single token and
+	// uses the current time for now
 	bool claim();
+
+	// Return the current number of tokens available
+	double get_tokens();
+
+	// Return the last time someone tried to claim a token.
+	uint64_t get_last_seen();
+
 private:
 
 	//
 	// The number of tokens generated per second.
 	//
-	uint64_t m_rate;
+	double m_rate;
 
 	//
 	// The maximum number of tokens that can be banked for future
 	// claim()s.
 	//
-	uint64_t m_max_tokens;
+	double m_max_tokens;
 
 	//
 	// The current number of tokens
 	//
-	uint64_t m_tokens;
+	double m_tokens;
 
 	//
 	// The last time claim() was called (or the object was created).