From c399f66db5eefaecce065d4f5ea7dcc725b8e106 Mon Sep 17 00:00:00 2001
From: jvoisin
Date: Thu, 21 Dec 2017 17:41:42 +0100
Subject: Improve a bit the documentation wrt. limitations

---
 README.md               |  2 ++
 doc/source/config.rst   | 21 +++++++++++++++++----
 doc/source/features.rst |  2 +-
 3 files changed, 20 insertions(+), 5 deletions(-)

diff --git a/README.md b/README.md
index ef922ca..16bc8b7 100644
--- a/README.md
+++ b/README.md
@@ -1,3 +1,5 @@
+# Snuffleupagus
+
 [![Build Status](https://travis-ci.org/nbs-system/snuffleupagus.svg?branch=master)](https://travis-ci.org/nbs-system/snuffleupagus)
 [![Coverity status](https://scan.coverity.com/projects/13821/badge.svg?flat=1)](https://scan.coverity.com/projects/nbs-system-snuffleupagus)
 [![CII Best Practices](https://bestpractices.coreinfrastructure.org/projects/1267/badge)](https://bestpractices.coreinfrastructure.org/projects/1267)
diff --git a/doc/source/config.rst b/doc/source/config.rst
index ceb23bb..5e323db 100644
--- a/doc/source/config.rst
+++ b/doc/source/config.rst
@@ -322,7 +322,7 @@ The ``param`` filter is also able to do some dereferencing:
 
 The ``filename`` filter requires a leading ``/``, since paths are absolutes (like ``/var/www/mywebsite/lib/parse.php``).
 If you would like to have only one configuration file for several vhost in different folders,
-you can use the the ``filename_r`` directive to match on the filename (like ``/lib/parse\.php``).
+you can use the ``filename_r`` directive to match on the filename (like ``/lib/parse\.php``).
 
 For clarity, the presence of the ``allow`` or ``drop`` action is **mandatory**.
 
@@ -333,9 +333,22 @@ For clarity, the presence of the ``allow`` or ``drop`` action is **mandatory**.
   more narrowed way later, the call will be denied,
   because it'll match the deny first.
 
-If you're paranoid, we're providing a php script to automatically generate
-hash of files containing dangerous functions,
-and blacklisting them everywhere else.
+If you're paranoid, we're providing a `php script
+<https://github.com/nbs-system/snuffleupagus/blob/master/scripts/generate_rules.php>`__
+to automatically generate hash of files containing dangerous functions, and
+blacklisting them everywhere else.
+
+Limitations
+^^^^^^^^^^^
+
+It's currently not possible to:
+
+- Hook every `language construct <https://secure.php.net/manual/en/reserved.keywords.php>`__,
+  because each of them requires a specific implementation.
+- Hook on the return value of user-defined functions
+- Use extra-convoluted rulesfor matching, like ``${$A}$$B->${'}[1]``, because if you're writing
+  things like this, odds are that you're doing something wrong anyway.
+
 
 Examples
 ^^^^^^^^
diff --git a/doc/source/features.rst b/doc/source/features.rst
index e560925..ee39682 100644
--- a/doc/source/features.rst
+++ b/doc/source/features.rst
@@ -274,7 +274,7 @@ disable them - at the risk of breaking critical features.
 Snuffleupagus allows the user to restrict usage of specific functions per file, or per
 file with a matching (sha256) hash, thus allowing the use of such functions **only** in the intended places.
 
-Furthermore, running the `following script <FIXME>`_  will generate an hash and line-based whitelist
+Furthermore, running the `following script <https://github.com/nbs-system/snuffleupagus/blob/master/scripts/generate_rules.php>`_  will generate an hash and line-based whitelist
 of dangerous functions, droping them everywhere else:
 
 
-- 
cgit v1.3