dhscanner-kbgen 1.0.0 → 1.0.1

raw patch · 2 files changed

+81/−80 lines, 2 filesPVP ok

version bump matches the API change (PVP)

API changes (from Hackage documentation)

Files

dhscanner-kbgen.cabal +1/−1
src/Kbgen.hs +80/−79

dhscanner-kbgen.cabal view

@@ -33,7 +33,7 @@         * explain in plain English your query's purpose
         * et voilà !
     
-version:            1.0.0
+version:            1.0.1
 license:            GPL-3.0-only
 license-file:       LICENSE
 author:             OrenGitHub

src/Kbgen.hs view

@@ -7,17 +7,26 @@ --     * from /various/ programming languages
 --     * each fact can be translated to a [Prolog](https://en.wikipedia.org/wiki/Prolog) fact
 --     * facts can be combined to create [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29)
---     * predictaes can be combined to formulate /security queries/
+--     * [predicates](https://en.wikipedia.org/wiki/Predicate_%28logic%29) can be combined to formulate /security queries/
 --
--- * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts describe relations between:
+-- * Facts describe relations between:
 --
 --     * code locations
 --     * const strings
 --     * const integers
 --
--- * [Prolog](https://en.wikipedia.org/wiki/Prolog) facts can be /combined/:
+-- * Code locations are capable of representing /all/ program entities
 --
---     * create /expressive/ queries from /simple/ facts
+--     * classes
+--     * methods
+--     * lambdas
+--     * annotations
+--     * arguments
+--     * parameters
+--     * etc.
+--
+-- * Facts can be /combined/:
+--
 --     * [conjunction](https://en.wikipedia.org/wiki/Logical_conjunction)
 --     * [disjunction](https://en.wikipedia.org/wiki/Logical_disjunction)
 --     * [negation](https://en.wikipedia.org/wiki/Negation)
@@ -81,65 +90,39 @@ import Fqn hiding ( content )
 
 -- |
--- * each fact is derived from a /single/ bitcode 'Bitcode.Instruction'
 --
--- * often, a single bitcode instruction will yield /more/ than one fact
---
-data Fact
-   = ArgCallCtor ArgForCall
-   | ParamNameCtor ParamName
-   | ClassNameCtor ClassName
-   | ArgForCallCtor ArgForCall
-   | ArgiForCallCtor ArgiForCall
-   | ConstStringCtor ConstString
-   | CallResolvedCtor CallResolved
-   | ConstBoolTrueCtor ConstBoolTrue
-   | MethodOfClassCtor MethodOfClass
-   | ClassNamedSuperCtor ClassNamedSuper
-   | ClassAnnotationCtor ClassAnnotation
-   | ParamiOfCallableCtor ParamiOfCallable
-   | KeywordArgForCallCtor KeywordArgForCall
-   | ParamResolvedTypeCtor ParamResolvedType
-   | ClassResolvedSuperCtor ClassResolvedSuper
-   | CallableAnnotationCtor CallableAnnotation
-   deriving ( Show, Generic, ToJSON, FromJSON )
-
--- |
---
--- __Description:__
---
--- Keyword argument for call
+-- __Name__
 --
--- __Prolog signature:__
+-- This is how the fact will look inside the Prolog file
 --
 -- @
 -- kb_keyword_arg_for_call( Keyword, Arg, Call ).
 -- @
---
--- __Code example ( Python ):__
+-- 
+-- __When should I use this fact__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
 --
--- Motivated by [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803)
--- ( [source code](https://github.com/hiyouga/LLaMA-Factory/commit/b3aa80d54a67da45e9e237e349486fb9c162b2ac) )
+-- Code snippet ( Python ):
 --
 -- @
 -- Popen(f'llamafactory-cli train {save_cmd(args)}', env=env, shell=True)
 -- @
 --
--- __Predicate example:__
---
--- Facts combined in this predicate:
+-- See complete source example: [here](https://github.com/hiyouga/LLaMA-Factory/commit/b3aa80d54a67da45e9e237e349486fb9c162b2ac)
 --
---     * 'CallResolved'
---     * 'KeywordArgForCall'
---     * 'ConstBoolTrue'
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-52803](https://nvd.nist.gov/vuln/detail/CVE-2024-52803) )
 --
 -- @
 -- subprocess_Popen_called_with_shell_eq_True( Call ) :-
---     kb_call_resolved( Call, \'subprocess.Popen\' ),
 --     kb_keyword_arg_for_call( \'shell\', TrueValue, Call ),
+--     kb_call_resolved( Call, \'subprocess.Popen\' ),
 --     kb_const_bool_true( TrueValue ).
 -- @
 --
+-- Other facts combined in this example predicate:
+--
+--     * 'CallResolved'
+--     * 'ConstBoolTrue'
+--
 data KeywordArgForCall = KeywordArgForCall
     Keyword -- ^
     Arg -- ^
@@ -148,31 +131,25 @@ 
 -- |
 --
--- __Description:__
---
--- Input parameter of some callable ( method, function, lambda ) has the specified resolved type
+-- __Name__
 --
--- __Prolog signature:__
+-- This is how the fact will look inside the Prolog file
 --
 -- @
 -- kb_param_has_resolved_type( Param, ResolvedType ).
 -- @
 --
--- __Code Example ( Golang ):__
+-- __When should I use this fact__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
 --
--- Motivated by [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380)
--- ( [source code](https://github.com/plentico/plenti/blob/01825e0dcd3505fac57adc2edf29f772d585c008/cmd/serve.go#L205) )
+-- Code snippet ( Golang ):
 --
 -- @
 -- func postLocal(w http.ResponseWriter, r *http.Request) { ... }
 -- @
 --
--- __Predicate example:__
---
--- Facts combined in this predicate:
+-- See complete source example: [here](https://github.com/plentico/plenti/blob/01825e0dcd3505fac57adc2edf29f772d585c008/cmd/serve.go#L205)
 --
---     * 'ParamResolvedType'
---     * 'ParamiOfCallable'
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-49380](https://nvd.nist.gov/vuln/detail/CVE-2024-49380) )
 --
 -- @
 -- looks_like_user_input( RequestParam ) :-
@@ -182,6 +159,10 @@ --     kb_param_i_of_callable( RequestParam, 1, Handler ).
 -- @
 --
+-- Other facts combined in this predicate:
+--
+--     * 'ParamiOfCallable'
+--
 data ParamResolvedType = ParamResolvedType
     Param -- ^
     ResolvedType -- ^
@@ -189,22 +170,15 @@ 
 -- |
 --
--- __Description:__
---
--- Class has the specified name
+-- __Name__
 --
--- __Prolog signature:__
+-- This is how the fact will look inside the Prolog file
 --
 -- @
 -- kb_class_name( Class, Name ).
 -- @
 --
--- __Code Example ( Python ):__
---
--- Motivated by [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995)
--- ( [source code](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10)
--- and see also [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
--- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15) )
+-- __When should I use this fact__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
 --
 -- @
 -- # authentication.py
@@ -215,24 +189,27 @@ -- class BaseHandler(RequestHandler): ...
 -- @
 --
--- __Writing a new predicate:__
---
--- Facts combined in this predicate:
+-- See complete source example [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/authentication.py#L10),
+-- [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L35)
+-- and [here](https://github.com/SickChill/sickchill/blob/846adafdfab579281353ea08a27bbb813f9a9872/sickchill/views/index.py#L15)
 --
---     * 'ClassResolvedSuper'
---     * 'ClassName'
---     * 'ClassNamedSuper'
+-- __Writing a predicate with this fact and others__ ( motivation: [CVE-2024-53995](https://nvd.nist.gov/vuln/detail/CVE-2024-53995) )
 --
 -- @
 -- skip_level_subclass_of( Subclass, \'tornado.web.RequestHandler\' ) :-
---     kb_class_resolved_super( Class, \'tornado.web.RequestHandler\' ),
 --     kb_class_name( Class, ClassType ),
---     kb_class_named_super( Subclass, ClassType ).
+--     kb_class_named_super( Subclass, ClassType ),
+--     kb_class_resolved_super( Class, \'tornado.web.RequestHandler\' ).
 -- @
 --
+-- Other facts combined in this predicate:
+--
+--     * 'ClassNamedSuper'
+--     * 'ClassResolvedSuper'
+--
 data ClassName = ClassName
     Class -- ^
-    Token.ClassName -- ^ 🔗 ( external link invalidated, use: [Token.ClassName](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html))
+    Token.ClassName -- ^
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 -- |
@@ -301,7 +278,7 @@ --
 data ParamName = ParamName
     Param -- ^
-    Token.ParamName -- ^ 🔗 ( external link invalidated, use: [Token.ParamName](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Token.html#t:ParamName) )
+    Token.ParamName -- ^ 
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 -- |
@@ -429,7 +406,7 @@ --
 data ConstString = ConstString
     ConstStr -- ^
-    Token.ConstStr -- ^ 🔗 ( external link invalidated, use: [Location](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html))
+    Token.ConstStr -- ^
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 data Arg = Arg Location deriving ( Show, Generic, ToJSON, FromJSON )
@@ -438,14 +415,14 @@ -- | Simply a wrapper around [Location](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html)
 -- 
 data Param = Param
-    Location -- ^ 🔗 ( external link invalidated, use: [Location](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html))
+    Location -- ^
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 -- |
 -- 
 -- Class is the code location defined in [Ast.StmtClassContent](https://hackage-content.haskell.org/package/dhscanner-ast-1.1.0/docs/Ast.html#t:StmtClassContent)
 data Class = Class
-    Location -- ^ 🔗 ( external link invalidated, use: [Location](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html))
+    Location -- ^
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 data CallResolved = CallResolved
@@ -467,10 +444,34 @@ 
 -- |
 data ResolvedType = ResolvedType
-    Fqn -- ^ 🔗 ( external link invalidated, use: [Fqn](https://hackage-.haskell.org/package/dhscanner-ast-1.1.0/docs/Location.html))
+    Fqn -- ^
     deriving ( Show, Generic, ToJSON, FromJSON )
 
 data ResolvedSuper = ResolvedSuper Fqn deriving ( Show, Generic, ToJSON, FromJSON )
+
+-- |
+-- * each fact is derived from a /single/ bitcode 'Bitcode.Instruction'
+--
+-- * often, a single bitcode instruction will yield /more/ than one fact
+--
+data Fact
+   = ArgCallCtor ArgForCall
+   | ParamNameCtor ParamName
+   | ClassNameCtor ClassName
+   | ArgForCallCtor ArgForCall
+   | ArgiForCallCtor ArgiForCall
+   | ConstStringCtor ConstString
+   | CallResolvedCtor CallResolved
+   | ConstBoolTrueCtor ConstBoolTrue
+   | MethodOfClassCtor MethodOfClass
+   | ClassNamedSuperCtor ClassNamedSuper
+   | ClassAnnotationCtor ClassAnnotation
+   | ParamiOfCallableCtor ParamiOfCallable
+   | KeywordArgForCallCtor KeywordArgForCall
+   | ParamResolvedTypeCtor ParamResolvedType
+   | ClassResolvedSuperCtor ClassResolvedSuper
+   | CallableAnnotationCtor CallableAnnotation
+   deriving ( Show, Generic, ToJSON, FromJSON )
 
 class Prologify a where prologify :: a -> String