benedmunds / inspekt

Inspekt is a PHP library that makes it easier to write secure web applications

Inspekt

License

LICENSE

Maintained by

Ben Edmunds benedmunds.com

Created by

Ed Finkler [email protected]

Version 0.6.3 2022-02-21

What Is Inspekt?

Inspekt is a comprehensive filtering and validation library for PHP.

Driving principles behind Inspekt

• Accessing user input via the PHP superglobals is inherently dangerous, because the "default" action is to retrieve raw, potentially dangerous data
• Piecemeal, "inline" filtering/validation done at various places in an application's source code is too error-prone to be effective
• The purpose of a library or framework is to make a programmer's job easier. Verbose and/or complex solutions should be avoided unless they are the only solution

Features of Inspekt

• 'Cage' objects that encapsulate input and require the developer to use the provided filtering and validation methods to access input data
• Automatic application of filtering as defined in a configuration file
• A library of static filtering and validation methods
• A simple, clear API
• No external dependencies

Documentation

User Docs

API Docs

How Do I Use Inspekt?

The best idea at the moment is to look at the Examples directory.

Quickly creating a cage for common input superglobals

<?php
use Inspekt\Inspekt;

/*
 * creates a cage for $_GET, $_POST, $_COOKIE, $_ENV, $_FILES, $_SERVER
 */
$superCage = Inspekt::makeSuperCage();

echo 'Digits:' . $superCage->server->getDigits('SERVER_SOFTWARE') . '<p/>';
echo 'Alpha:' . $superCage->server->getAlpha('SERVER_SOFTWARE') . '<p/>';
echo 'Alnum:' . $superCage->server->getAlnum('SERVER_SOFTWARE') . '<p/>';
echo 'Raw:' . $superCage->server->getRaw('SERVER_SOFTWARE') . '<p/>';

Creating a cage from an arbitrary array

<?php
/**
 * Demonstration of:
 * - use of static filter methods on arrays
 * - creating a cage on an arbitrary array
 * - accessing a deep key in a multidim array with the "Array Query" approach
 */


require_once dirname(__FILE__) . "/../vendor/autoload.php";

use Inspekt\Cage;

$d = array();
$d['input'] = '<img id="475">yes</img>';
$d['lowascii'] = '������� � � � ';
$d[] = array('foo', 'bar<br />', 'yes<P>', 1776);
$d['x']['woot'] = array(
    'booyah' => 'meet at the bar at 7:30 pm',
    'ultimate' => '<strong>hi there!</strong>',
);
$d['lemon'][][][][][][][][][][][][][][] = 'far';


$d_cage = Cage::Factory($d);

var_dump($d_cage->getAlpha('/x/woot/ultimate'));

var_dump($d_cage->getAlpha('lemon/0/0/0/0/0/0/0/0/0/0/0/0/0'));

$x = $d_cage->getAlpha('x');
var_dump($x);

$x = $d_cage->getAlpha('input');
var_dump($x);

Calling an individual validation method

<?php
require_once dirname(__FILE__) . "/../vendor/autoload.php";

use Inspekt\Inspekt;

$rs = Inspekt::isUri('http://www.w3.org/2001/XMLSchema');
var_dump($rs);

How Do I Run Tests

Install PHPUnit, cd to the root dir of Inspekt, and type

phpunit tests/

Changelog

Version 0.6.4 - 2022-02-21

• Release to force a composer update

Version 0.6.3 - 2022-02-21

• Bug fix for array_key_exists using ArrayObject instead of Array

Version 0.6.2 - 2021-03-12

• Bug fix for isInt()

Version 0.6.1 - 2016-03-03

• Bug fix for isFloat()

Version 0.6.0 - 2014-11-08

• Backwards-compatibility breaks! Be aware! Read examples!
• removed CodeIgniter helper
• removed all session cage code
• refactor for PSR2 compliance, including namespaces (BC BREAK)
• drop mysql for mysqli escaping calls

2014-04-14

• Added composer.json file

Version 0.4.1 - 2010-01-15

• Inspekt_Cage::keyExists now returns boolean again, unless second param is TRUE (then it returns the value if key exists)
• fixed a bunch of missing public/protected definitions
• renamed Inspekt_CageTest.php to CageTest.php so phpunit would load it correctly
• wrote a couple unit tests for Inspekt_Cage::testAlnum

Version 0.4.0 - 2009-11-15

• added new way to add cage accessor methods by extending AccessorAbstract and registering with cage object
• added Inspekt_Cage::addAccessor() and Inspekt_SuperCage::addAccessor()
• modified Examples/extending.php to demonstrate adding new accessor methods
• added HTMLPurifier integration capability and new cage filter getPurifiedHTML()
• added a library for CodeIgniter to use Inspekt in the standard Input object
• make Inspekt::isArrayObject() and Inspekt::isArrayOrArrayObject() public
• added __call() to Inspekt_Cage so we can handle user-defined accessor methods
• added underscore to path portion of isUri() (Nick Ramsay)
• added a new folder for Integration_helpers
• commented out include for Inspekt/Cage/Session in Cage.php because it caused probs generating Cage test skeleton
• made PHPUnit Inspekt_Cage test skeleton
• added simple example for a wrapper that will pull from GET or POST

Version 0.3.5 - 2009-07-18

• refactored and reworked some examples; added db escaping examples
• did some work to get isInt to handle 64 bit integers better (more to do)
• fixed bug in isOneOf where a string pattern wasn't converted properly
• removed some incorrectly optional params for methods
• isRegex now correctly returns a boolean, not an Int
• added missing cage methods getROT13, noTagsOrSpecial, escMySQL, escPgSQL, escPgSQLBytea
• added many more unit tests

Version 0.3.4 - 2009-07-18

• Added Inspekt::getROT13()
• Added Inspekt::escMySQL()
• Added Inspekt::escPgSQL()
• Added Inspekt::escPgSQLBytea()
• Now arrays are only converted to ArrayObjects by cages; arrays passed into static filter calls are returned as arrays.
• More unit tests, and tests moved into InspektTest.php (removed Tests/ subdir)
• cleanup in Inspekt_SuperCage to fix STRICT notices

Version 0.3.3 - 2009-07-18

• Caged properties can now be iterated over b/c we're implementing ArrayObject (Matt McKeon)
• added a number of @assert tests for phpunit testing
• cleaned up function declarations so they would not raise STRICT notices
• leveraged Filter Extention in a couple filter methods; can be turned off with Inspekt::useFilterExt()
• added filter method Inspekt::noTagsOrSpecial() that strips tags, encodes '"&<>, and all low ascii chars (< 32)
• upped recursion limit to 15
• Inspekt::_walkArray will now convert a plain array into an ArrayObject (should it always? Not sure)
• filter methods will now use Inspekt::isArrayOrArrayObject() to determine if they need to walk the array
• fixed some require_once statements to use dirname() resolution so fewer path issues pop up (they showed up when using phpunit)

Version 0.3.2 - 2009-06-22

PHP5 now required, bug fixes for transposed params

Version 0.3.1 - 2008-02-08

Disables processing of $_SESSION

Version 0.3.0 - 2008-01-16

Final OWASP milestone release

Version 0.1 - 2007-05-19

Initial Release

inspekt's Issues

float validation failure with trailing Zero

Seems that strings with trailing Zero do not validate correctly

Inspekt::isFloat("1.60") === false
floatval() trims the trailing Zero
strval(1.6) !== "1.60"

inspekt.org is broken for me

Seems to be some kind of 301 redirect looping and an issue with the SSL certificate.

Ambiguous references to ../vendor/autoload.php

I'm curious where these references are actually pointing to..

Interestingly enough, I happen to have a 'vendor/autoload.php' from authorize.net sdk, but I somehow don't think this is what you're referring to?

html/inspekt/Examples# grep vendor *
config.php:require_once dirname(FILE) . "/../vendor/autoload.php";
db_escaping.php:require_once dirname(FILE) . "/../vendor/autoload.php";
extending.php:require_once dirname(FILE) . "/../vendor/autoload.php";
filter_array_cage.php:require_once dirname(FILE) . "/../vendor/autoload.php";
filter_form_input.php:require_once dirname(FILE) . "/../vendor/autoload.php";
filter_static_methods.php:require_once dirname(FILE) . "/../vendor/autoload.php";
filter_superglobals.php:require_once dirname(FILE) . "/../vendor/autoload.php";
formtest.php:require_once dirname(FILE) . "/../vendor/autoload.php";
get_or_post.php:require_once dirname(FILE) . "/../vendor/autoload.php";
htmlpurifier.php:require_once dirname(FILE) . "/../vendor/autoload.php";
iterate_cage.php:require_once dirname(FILE) . "/../vendor/autoload.php";
supercage.php:require_once dirname(FILE) . "/../vendor/autoload.php";
uri_tester.php:require_once dirname(FILE) . "/../vendor/autoload.php";

Automatic Type Conversion

$_POST['b'] = '0';
$cage_POST = Inspekt::makePostCage();
var_dump( $cage_POST->testAlnum ('b') ) <--- this should be 0 but FALSE.

$_POST['b'] = '2009-12-25';
$cage_POST = Inspekt::makePostCage();
var_dump( $cage_POST->testGreaterThan ('b') , 25 ) <--- this should be FALSE but '2009-12-25'.

$_POST['b'] = '0';
$cage_POST = Inspekt::makePostCage();
var_dump( $cage_POST->testLessThan ('b') , 25 ) <--- this should be 0 but FALSE.

no apparent way to test for numbers, letters, and spaces

trying to use inspekt in combination with a validator library to ensure security in form input.

use case is, input field is 'full name'. so, it fails testAlnum.

maybe needs a testNoTagsOrSpecial.

also, testEmail fails on some new TLDs.

Validating email subdomain, max 6 chars (Inspekt.php#L84)

Just a heads up really for isEmail($value):

The current list of subdomains (http://data.iana.org/TLD/tlds-alpha-by-domain.txt), many are over 6 chars in length.

filter_superglobals.php example enhancement

As title, it looks like this example code looks strange when printing some messages via echo.

Here are the code snippets I mention:

......
echo 'Digits:' . $serverCage->getDigits('SERVER_SOFTWARE') . '<p/>';
echo 'Alpha:' . $serverCage->getAlpha('SERVER_SOFTWARE') . '<p/>';
echo 'Alnum:' . $serverCage->getAlnum('SERVER_SOFTWARE') . '<p/>';
echo 'Raw:' . $serverCage->getRaw('SERVER_SOFTWARE') . '<p/>';
......

And these code snippets should be changed into:

......
echo 'Digits:' . $serverCage->getDigits('SERVER_SOFTWARE') . '<br/>';
echo 'Alpha:' . $serverCage->getAlpha('SERVER_SOFTWARE') . '<br/>';
echo 'Alnum:' . $serverCage->getAlnum('SERVER_SOFTWARE') . '<br/>';
echo 'Raw:' . $serverCage->getRaw('SERVER_SOFTWARE') . '<br/>';
......

I think it means add end of line HTML tag when presenting the messages on the we page :).

Different results using local and composer loaded Inspekt

When caging my own array and then checking an element of that array I get different result depending on whether I am using the version of Inspekt downloaded from github as opposed to the version from composer.

For example this works without errors:

<?php
    require_once('inc/Inspekt.php');

    $test = array();
    $test['params'][] = "hello";

    // cage the array
    $params_cage = Inspekt_Cage::Factory($test);
    $one = $params_cage->getAlnum('params/0');
    $two = $params_cage->getInt('params/1');
 ?>

However, if I run the following:

<?php
    require __DIR__ . '/vendor/autoload.php';

    // Inspekt initialisation
    use Inspekt\Inspekt;
    use Inspekt\Cage;

    $test = array();
    $test['params'][] = "hello";

    // cage the array
    $params_cage = Cage::Factory($test);
    $one = $params_cage->getAlnum('params/0');
    $two = $params_cage->getInt('params/1');
?>

Gives the following error:

Fatal error: Uncaught exception 'Inspekt\Exception' with message 'Key '1' does not exist' in /home/ubuntu/workspace/vendor/funkatron/inspekt/src/Inspekt/Cage.php:992 
Stack trace: #0 /home/ubuntu/workspace/vendor/funkatron/inspekt/src/Inspekt/Cage.php(985): Inspekt\Cage->getValueRecursive(Array, Object(ArrayObject), 1) 
#1 /home/ubuntu/workspace/vendor/funkatron/inspekt/src/Inspekt/Cage.php(954): Inspekt\Cage->getValueRecursive(Array, Object(ArrayObject)) 
#2 /home/ubuntu/workspace/vendor/funkatron/inspekt/src/Inspekt/Cage.php(394): Inspekt\Cage->getValue('params/1') 
#3 /home/ubuntu/workspace/it.php(15): Inspekt\Cage->getInt('params/1') 
#4 {main} thrown in /home/ubuntu/workspace/vendor/funkatron/inspekt/src/Inspekt/Cage.php on line 992

Given that you cannot check for null on a caged array (I don't think) this latter functionality makes caging of your arrays less useful.

keyExists, getInt and getRaw fail when value to get is equal to zero

I'm trying to validate a form using Inspekt. One of the fields I'm trying to validate is a select box with values such as -1, 0, 1, 2, etc. I have set -1 as my invalid case, and all other cases are valid. However, when trying to get the value of the select, it works for any value except 0, which makes all of the above mentioned methods to fail (i.e.: return false).

I found it weird, so I thought I would mention it here. Any ideas?

Inspekt::isIp() should support ipv6

preeeeety much what it says.

isZip() Regex

The pattern for the isZip() method could be shortened to: /^\d{5}(?:-\d{4})?$/, ?: isn't strictly necessary.

array_key_exists Problem with ArrayObject on PHP8

Using array_key_exists with Objects no longer works on PHP8.

I get this error: funkatron/inspekt/src/Inspekt/Cage.php(943) -- array_key_exists(): Argument #2 ($array) must be of type array, ArrayObject given

Can be resolved using:
return $exists = array_key_exists($key, (array) $this->source);
or
return $exists = property_exists($this->source, $key);

If you want i can create a PR with one of those changes.