2 files changed, 145 insertions(+), 5 deletions(-)

M man/man1/sf.1
A man/man5/sf.conf.5

@@ 18,7 18,7 @@
 .Sh DESCRIPTION
 The
 .Nm
-utility enforces privileges in your sql database according to
+utility applies privileges in your sql database according to
 .Xr sf.conf 5 .
 It wipes existing privileges and re-applies new ones, whitelisting and
 blacklisting access to databases, tables, statements, and columns on a per-user


@@ 27,19 27,19 @@ basis.
 is declarative; it will produce the same privileges on each run and is safe to
 run multiple times.
 .Pp
-Only MySQL v5.7 is currently supported. MariaDB is not compatible.
+Only MySQL v5.7 is currently supported.  MariaDB is not compatible.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl d
-Dry run. Print JSON of all denied columns to stdout without modifying the
+Dry run.  Print JSON of all denied columns to stdout without modifying the
 database directly.
 .It Fl f Ar file
 Update the current privileges with the rules contained in
 .Ar file .
 This
 .Ar file
-may contain macros, tables, and privilege rules.
+may contain macros and privilege rules.
 .It Fl p Ar password
 The password for the SQL
 .Ar user .


@@ 59,7 59,7 @@ SQL server name for TLS.
 .Pp
 .Bl -tag -width Ds
 .It Fl u Ar user
-User in the SQL database. Must have the GRANT privilege.
+User in the SQL database.  Must have the GRANT privilege.
 .El
 .Sh EXIT STATUS
 .Ex -std

@@ 0,0 1,140 @@
+.Dd $Mdocdate$
+.Dt SF.CONF 5
+.Os
+.Sh NAME
+.Nm sf.conf
+.Nd sf configuration file
+.Sh DESCRIPTION
+The
+.Xr sf 1
+utility applies privileges in your sql database according to rules or
+definitions specified in
+.Nm .
+.Pp
+This is an overview of the sections in this manual page:
+.Bl -inset
+.It Sx RULES
+provides rules for allowing and denying access to data.
+.It Sx STATEMENTS
+provides a complete list of allowed statements in rules.
+.It Sx EXAMPLES
+provides some example rulesets.
+.El
+.Pp
+The current line can be extended over multiple lines using a backslash
+.Pq Sq \e .
+Comments can be put at the start of lines in the file using a hash mark
+.Pq Sq # ,
+and extend to the end of the current line.
+.Pp
+Macros can be defined that will later by expanded in context.  Macro names must
+start with a letter, digit, or underscore and may contain any of those
+characters.
+Macro names may not be reserved words (for example
+.Ic deny ,
+.Cm all ,
+.Cm any ) .
+.Pp
+The top-most rule in
+.Nm
+must be
+.Ic deny Cm all .
+This will ensure that the same privileges are applied on each run, allowing you
+to run
+.Xr sf 1
+multiple times and get the same behavior on each run.  This requirement is
+enforced by
+.Xr sf 1 .
+.Sh RULES
+.Xr sf 1
+has the ability to
+.Ic deny
+and
+.Ic allow
+users access to data in a SQL server.  Filter rules determine which of these
+actions are taken; filter parameters specify the users, databases, tables,
+statements and columns to which a rule applies.
+.Pp
+The rules are applied in sequential order, from first to last.  If a later rule
+overrides an earlier rule, the last rule's behavior will apply.
+.Pp
+Most parameters are optional.  If a parameter is specified, the rule only
+applies to that user, database, table, statement, or column.
+.Pp
+The following actions can be used in the filter:
+.Bl -tag -width Ds
+.It Cm deny Pq Cm all | Ar user
+The access is denied across all databases for the user.
+.It Cm allow Pq Cm all | Ar user
+The access is allowed across all databases for the user.
+.It Cm db Pq Cm any | Cm Ar database
+Restrict or allow access to a database.
+.It Cm table Pq Cm any | Cm Ar table
+Restrict or allow access to a table.
+.It Cm statement Pq Cm any | Cm Ar statement
+Restrict or allow access to a statement such as
+.Cm select ,
+.Cm insert , No or
+.Cm alter .
+.It Cm column Pq Cm any | Ar column
+Restrict or allow access to a column.  Removing the column definition from the
+rule is equivalent to
+.Cm column Cm any .
+.Sh STATEMENTS
+.Pp
+Any of the following statements may be used in rules following the
+.Cm statement
+directive:
+.Bd -literal -offset indent
+alter
+create
+delete
+drop
+event
+execute
+file
+index
+insert
+process
+proxy
+references
+reload
+select
+shutdown
+super
+trigger
+update
+usage
+.Sh EXAMPLES
+In this example, we use macros to store variables and lists which will be
+replaced or expanded at runtime.
+.Bd -literal -offset indent
+read  = { bob jim }
+write = _dashboard
+crud  = { select insert update delete }
+
+deny all
+allow root
+
+allow $read db any table any statement select
+deny $read db dashboard table admins statement any \e
+	column password
+deny $read db dashboard table { password_resets oauth_tokens }
+allow $write db any table any statement $crud
+.Ed
+.Pp
+First we
+.Cm deny all
+to reset privileges in the database, then we selectively allow users to access
+it.  The root user is given full privileges, and since it does not have any
+deny rules apply to it in the ruleset, it is also given the
+.Cm grant option .
+.Pp
+The users bob and jim will each have access to run select queries across any
+database and table, but we specifically deny access to the password column in
+the admins table and the entirety of the password_resets and oauth_tokens
+tables.  The user _dashboard will have privileges to run select, insert,
+update, and delete throughout the database.  We use \e to extend our rule onto
+the next line.
+.Sh SEE ALSO
+.Xr sf 1