Merge pull request #38 from ebranca/dev

add docs

docs/docs/concerns/builtin/numeric_overflow.md

@@ -0,0 +1,91 @@
+Numeric overflow in builtin function xrange
+===========================================
+
+Classification
+--------------------------
+
+* **Affected Components** : builtin
+
+* **Operating System** : Linux
+
+* **Python Versions** : 2.6.x, 2.7.x, 3.1.x, 3.2.x
+
+* **Reproducible** : Yes
+
+
+Source code 
+--------------------------
+
+```python
+import sys
+
+N = 2 ** 63
+
+for n in xrange(N):
+    print n
+
+sys.exit(0)
+
+```
+
+
+Steps to Produce/Reproduce
+--------------------------
+
+To reproduce the problem copy the `source code` in a file and execute the script using the following command syntax:
+
+```python
+$ python -OOBRtt test.py
+```
+
+Alternatively you can open python in interactive mode:
+
+```python
+$ python -OOBRtt <press enter>
+```
+Then copy the lines of code into the interpreter.  
+
+
+Description
+-----------
+
+The execution of the test code will produce an ```Overflow``` error as the object we are trying to load is bigger than the maximum object supported natively by the operating system.
+
+```
+Traceback (most recent call last):
+  File "test.py", line 5, in <module>
+    for n in xrange(N):
+OverflowError: Python int too large to convert to C long
+```
+
+Even if this behaviour is "by design" and expected, this condition is not detected by the interpreter and a numeric overflow is generated by the python core libraries.
+
+This happens because ```xrange``` uses "Plain Integer Objects" created by the OS and cannot accept objects of arbitrary length.
+
+The problem of numeric length can be easily solved by using python "long integer object“, the underlying problem of the numeric Overflow must be fixed in the core libraries.
+
+
+Workaround
+-----------
+
+
+We are not aware on any **easy** solution other than trying to avoid using ```'xrange'``` in cases like the one examined.
+
+But a **PERMANENT SOLUTION** is available, just use python "long integer object“ that will allow numbers of arbitrary length as the limit will be the system's memory.
+
+
+Secure Implementation
+-----------
+
+
+##### WORK IN PROGRESS
+
+
+References
+-----------
+
+[Python builtins][01]
+[01]:https://docs.python.org/2/library/functions.html
+
+
+

docs/docs/concerns/builtin/overflow_len.md

@@ -0,0 +1,152 @@
+Overflow in len function
+========================
+
+Classification
+--------------------------
+
+* **Affected Components** : builtin
+
+* **Operating System** : Linux
+
+* **Python Versions** : 2.6.x, 2.7.x, 3.1.x, 3.2.x
+
+* **Reproducible** : Yes
+
+
+Source code 
+--------------------------
+
+```python
+class A(object):
+    def __len__(self): 
+        return 100 ** 100
+
+class B(object):
+    def __len__(self): 
+        return 2L
+
+class C:
+    def __len__(self): 
+        return 100 ** 100
+
+class D:
+    def __len__(self): 
+        return 2L
+
+try:
+    len(A())
+    print """OK: 'class A(object)' with 'return 100 ** 100' - len calculated"""
+except Exception as e:
+    print """KO: 'class A(object)' with 'return 100 ** 100' - len raise Error: """ + repr(e,)
+
+try:
+    len(B())
+    print """OK: 'class B(object)' with 'return 2L' - len calculated"""
+except Exception as e:
+    print """KO: class B(object) with return 2L - len raise Error: """ + repr(e,)
+
+try:
+    len(C())
+    print """OK: 'class C' with 'return 100 ** 100' - len calculated"""
+except Exception as e:
+    print """KO: 'class C' with 'return 100 ** 100' - len raise Error: """ + repr(e,)
+
+try:
+    len(D())
+    print """OK: 'class C' with 'return 2L' - len calculated"""
+except Exception as e:
+    print """KO: 'class C' with 'return 2L' - len raise Error: """ + repr(e,)
+```
+
+
+Steps to Produce/Reproduce
+--------------------------
+
+To reproduce the problem copy the `source code` in a file and execute the script using the following command syntax:
+
+```python
+$ python -OOBRtt test.py
+```
+
+Alternatively you can open python in interactive mode:
+
+```python
+$ python -OOBRtt <press enter>
+```
+Then copy the lines of code into the interpreter.  
+
+
+Description
+-----------
+
+The source code tets the ability of python to check the length of an object.
+
+When the source code is executed 
+
+```python
+$ python -OOBRttu test.py 
+```
+
+we have the ***same results both python 2.6.x and 2.7.x*** as follow:
+
+```python
+KO: 'class A(object)' with 'return 100 ** 100'
+Error: OverflowError('long int too large to convert to int',)
+
+OK: 'class B(object)' with 'return 2L' - len calculated
+
+KO: 'class C' with 'return 100 ** 100'
+Error: TypeError('__len__() should return an int',)
+
+KO: 'class C' with 'return 2L'
+Error: TypeError('__len__() should return an int',)
+```
+
+in this case the ```len()``` function in python does not check for the legth of the object and does not use "python int objects" (unlimited) and this can cause an ```Overflow``` error as the object may contain the actual `.length` property.
+
+The reason of this is beacuse ```len(obj)``` is implemented using PyObject_Size(), which in turn it stores the result into a Py_ssize_t, and this object is limited to sys.maxsize (```2**31-1``` for 32bit or ```2**63-1``` for 64bit systems).
+
+And when the length of the object is bigger then the maximum size of an **integer** object in python, the type of the object changes to **long**.
+
+Even this condition is not checked in the core libraries therefore an unexpected ```TypeError``` is generated.
+
+
+
+Workaround
+-----------
+
+
+We are not aware on any **easy** solution other than writing a custom library to handle the described cases.
+
+
+Secure Implementation
+-----------
+
+
+##### WORK IN PROGRESS
+
+
+References
+-----------
+
+[Python built-in functions][01]
+[01]:https://docs.python.org/2/library/functions.html
+
+
+[Python Classes][02]
+[02]:https://docs.python.org/2/tutorial/classes.html
+
+
+[Python bug 12159][03]
+[03]:http://bugs.python.org/issue12159
+
+
+[Python bug 15718][04]
+[04]:http://bugs.python.org/issue15718
+
+
+[Python bug 21444][05]
+[05]:http://bugs.python.org/issue21444
+
+
+

docs/docs/concerns/builtin/unsafe_string.md

@@ -0,0 +1,99 @@
+Unsafe String interpretation if using input() function
+=======================================================
+
+Classification
+--------------------------
+
+* **Affected Components** : builtins
+
+* **Operating System** : Linux
+
+* **Python Versions** : 2.6.x, 2.7.x
+
+* **Reproducible** : Yes
+
+
+Source code 
+--------------------------
+
+```python
+Secret = "A SECRET DATA"
+Public = "a BANANA"
+
+value = input("Please enter your age ")
+print "There are",value,
+print "monkeys looking for",Public
+```
+
+
+Steps to Produce/Reproduce
+--------------------------
+
+To reproduce the problem copy the `source code` in a file and execute the script using the following command syntax:
+
+```python
+$ python -OOBRtt test.py
+```
+
+Alternatively you can open python in interactive mode:
+
+```python
+$ python -OOBRtt <press enter>
+```
+Then copy the lines of code into the interpreter.  
+
+
+Description
+-----------
+
+The script will ask the user to provide a number, and if the user provides **ONLY** a number then nothing happens.
+
+```
+python -OOBRtt test.py
+Please enter your age 32
+There are 32 monkeys looking for a BANANA
+```
+
+But if the user provides something different, for example a python command as ```dir()```, the string is interpreted and executed:
+
+```
+python -OOBRtt test.py
+Please enter your age dir()
+There are ['Public', 'Secret', '__builtins__', '__doc__', '__file__', '__name__', '__package__'] monkeys looking for a BANANA
+```
+In this case using ```dir()``` allow us to see “most” of the attributes of an object.
+
+Is also possible to provie the name of a variable, in this case we provide ```SECRET``` as this is the name of the variable that should not be accessible.
+
+```
+python -OOBRtt test.py
+Please enter your age Secret
+There are A SECRET DATA monkeys looking for a BANANA
+```
+
+***What you type as input is interpreted through an expression and the result is saved into your target variable with no control or limits.***
+
+Workaround
+-----------
+
+
+We are not aware on any **easy** solution other than trying to avoid using the function ```'input'``` in cases like the one examined.
+
+
+
+Secure Implementation
+-----------
+
+
+##### WORK IN PROGRESS
+
+
+References
+-----------
+
+[Python builtins][01]
+[01]:https://docs.python.org/2/library/functions.html
+
+
+
+