osquery: the schedule name is not the SQL

The name is a label in the config

Each scheduled result carries a name field. That string is the key in the schedule, the one a person chose when they wrote the config. It is not the SQL, and it does not list the columns. A key called listeners can select anything the author typed.

The columns object is what that run returned. It is the evidence of which fields came back. The key is only how you find the statement in a config.

The statement can change under the same key

Someone can edit the SQL and keep the key. Lines from last week still say the old key. They were produced by whatever statement was loaded then, not by the file on disk today. If you do not have that revision, write “SQL not attached.” Do not paste today’s statement under last week’s line.

A config commit id, a file hash, or a copy of the statement stored with the log is what makes the line repeatable. The key alone does not.

What to file

File the schedule key, unixTime, host identifier, and action. File the SQL only from the config revision you can point at, with that revision named. If you cannot point at one, say the statement is not in the log. Do not describe columns the columns object does not contain, even if the key’s name suggests them.

Worked case: a key that used to mean more

A line named net_listeners at unixTime 1793628903 has columns name and port only. Today’s config under that same key also selects the path. A draft says the path was /usr/sbin/sshd because that is what the key means now.

The note quotes the key, the time, and the two columns that are present. It says the SQL for that run was not attached, so today’s path column is not part of this line. The path is omitted, not filled in.

Snippet

name: net_listeners
unixTime: 1793628903
columns present: name, port
SQL for this line: not attached
today's config: also selects path
write: do not add path to this line

Diagram

The schedule key versus the statement

The log stores the key. The SQL lives in a config you must cite.

On the log line

name. The schedule key

columns. The fields that run returned

unixTime. When that result was logged

Not on the log line

SQL. Unless you attach the config revision

A later edit. Today’s statement is a different text

Missing columns. Not implied by the key’s name

Check yourself

1. What is the name field on an osqueryd result?

2. The key is unchanged and the SQL was edited later. Which statement produced an older line?

3. The columns object has no path, and the key is net_listeners. What may you write for path?