diff --git a/dhscanner-kbapi.cabal b/dhscanner-kbapi.cabal --- a/dhscanner-kbapi.cabal +++ b/dhscanner-kbapi.cabal @@ -28,7 +28,7 @@ fundamental modifications to the structure or specification of code facts. -version: 1.0.7 +version: 1.0.8 license: GPL-3.0-only license-file: LICENSE author: OrenGitHub diff --git a/json-schema-creator/Main.hs b/json-schema-creator/Main.hs --- a/json-schema-creator/Main.hs +++ b/json-schema-creator/Main.hs @@ -51,6 +51,13 @@ instance ToSchema FoundAuthenticatedHttpGetHandlerRequestObject instance ToSchema FoundAuthenticatedHttpGetHandlerRequestObjectMatch +instance ToSchema UnauthenticatedHttpPutHandlerRequestObject +instance ToSchema FoundUnauthenticatedHttpPutHandlerRequestObject +instance ToSchema AuthenticatedHttpPutHandlerRequestObject +instance ToSchema FoundAuthenticatedHttpPutHandlerRequestObject +instance ToSchema FoundAuthenticatedHttpPutHandlerRequestObjectMatch +instance ToSchema FoundHttpPutHandlerRequestObjectMatch + instance ToSchema CommentsInFunction instance ToSchema FoundCommentsInFunction instance ToSchema Comment @@ -63,6 +70,18 @@ instance ToSchema DataFlowPath instance ToSchema FoundDataFlowPath + +instance ToSchema SqlSinkKind +instance ToSchema SqlSinkKindCount +instance ToSchema ControlFlowReachableSqlSink +instance ToSchema FoundControlFlowReachableSqlSink +instance ToSchema FoundControlFlowReachableSqlSinkMatch + +instance ToSchema FileActionKind +instance ToSchema FileActionKindCount +instance ToSchema ControlFlowReachableFileActionSink +instance ToSchema FoundControlFlowReachableFileActionSink +instance ToSchema FoundControlFlowReachableFileActionSinkMatch schemaWithDefs :: ToSchema a => Proxy a -> Value schemaWithDefs p = diff --git a/src/Content.hs b/src/Content.hs --- a/src/Content.hs +++ b/src/Content.hs @@ -87,12 +87,10 @@ -- @utils_early_return_null_on_missing_request_header_value@. -- -- * @ByAllButOneBadReturn@ \- the authenticating function's body --- shape is "K-1 bad-http returns + 1 parser-injected fall-through" --- (e.g. formbricks @checkAuth@ : returns --- @responses.notAuthenticatedResponse()@ / --- @responses.unauthorizedResponse()@ in every failure path and --- falls through on success). No payload \- the evidence /is/ the --- shape, and the callable\'s name is already carried by +-- shape is "K-1 bad-http returns + 1 parser-injected fall-through" : +-- every failing path emits an error response, the single success +-- path falls through implicitly. No payload \- the evidence /is/ +-- the shape, and the callable\'s name is already carried by -- @foundAuthenticatedHttpPostHandlerAuthenticatingFunctionName@ -- ( or its GET twin ) on the enclosing match record. data AuthEvidence @@ -229,6 +227,82 @@ } deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) +-- | Symmetric PUT variant of 'UnauthenticatedHttpPostHandlerRequestObject'. +-- Enumerates HTTP PUT handlers whose bodies contain /no/ call to any +-- recognized authenticating function. +-- +-- Adding any other HTTP verb ( PATCH, DELETE, HEAD, OPTIONS, ... ) is +-- a pure leaf addition : mirror this block, add a new Query +-- constructor + a new KB-side clause + a new queryengine handler. +-- No existing consumer needs to change. +data UnauthenticatedHttpPutHandlerRequestObject + = UnauthenticatedHttpPutHandlerRequestObject + { + unauthenticatedHttpPutHandlerRequestObjectUrlParts :: [ String ], + unauthenticatedHttpPutHandlerRequestObjectLimit :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Result payload for 'UnauthenticatedHttpPutHandlerRequestObject'. +-- Reuses 'FoundHttpPutHandlerRequestObjectMatch' because an +-- unauthenticated PUT handler carries no auth metadata to surface -- +-- symmetric to how 'FoundUnauthenticatedHttpPostHandlerRequestObject' +-- reuses 'FoundHttpPostHandlerRequestObjectMatch'. +data FoundUnauthenticatedHttpPutHandlerRequestObject + = FoundUnauthenticatedHttpPutHandlerRequestObject + { + foundUnauthenticatedHttpPutHandlerRequestObjectTotal :: Word, + foundUnauthenticatedHttpPutHandlerRequestObjectMatches :: [ FoundHttpPutHandlerRequestObjectMatch ] + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Symmetric PUT variant of 'AuthenticatedHttpPostHandlerRequestObject'. +-- Same @AuthEvidence@ catalog + @AuthFuncName@ metadata as the POST +-- twin; see the POST record's haddock for the tagged-union rationale. +data AuthenticatedHttpPutHandlerRequestObject + = AuthenticatedHttpPutHandlerRequestObject + { + authenticatedHttpPutHandlerRequestObjectUrlParts :: [ String ], + authenticatedHttpPutHandlerRequestObjectLimit :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +data FoundAuthenticatedHttpPutHandlerRequestObject + = FoundAuthenticatedHttpPutHandlerRequestObject + { + foundAuthenticatedHttpPutHandlerRequestObjectTotal :: Word, + foundAuthenticatedHttpPutHandlerRequestObjectMatches :: [ FoundAuthenticatedHttpPutHandlerRequestObjectMatch ] + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | A match for an authenticated PUT handler request object query. Same +-- shape as 'FoundAuthenticatedHttpPostHandlerRequestObjectMatch', with +-- @PutHandler@ substituted for @PostHandler@ throughout the field +-- naming to keep POST/GET/PUT results distinguishable at the JSON layer. +data FoundAuthenticatedHttpPutHandlerRequestObjectMatch + = FoundAuthenticatedHttpPutHandlerRequestObjectMatch + { + foundAuthenticatedHttpPutHandlerLocation :: Location, + foundAuthenticatedHttpPutHandlerRequestObjectLocation :: Location, + foundAuthenticatedHttpPutHandlerRequestObjectMatchUrl :: String, + foundAuthenticatedHttpPutHandlerAuthenticatingFunctionName :: String, + foundAuthenticatedHttpPutHandlerAuthEvidence :: AuthEvidence + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | A match for an ( unauthenticated ) PUT handler request object query. +-- Same shape as 'FoundHttpPostHandlerRequestObjectMatch', with +-- @PutHandler@ substituted for @PostHandler@ throughout the field +-- naming to keep POST/PUT results distinguishable at the JSON layer. +data FoundHttpPutHandlerRequestObjectMatch + = FoundHttpPutHandlerRequestObjectMatch + { + foundHttpPutHandlerLocation :: Location, + foundHttpPutHandlerRequestObjectLocation :: Location, + foundHttpPutHandlerRequestObjectMatchUrl :: String + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + data CommentsInFunction = CommentsInFunction { @@ -298,5 +372,185 @@ = FoundDataFlowPath { foundDataFlowPathPath :: Maybe [ Location ] + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Enumeration query \- SQL sinks control-flow-reachable from an +-- entry point. +-- +-- Coarse tier of the coarse-to-fine reachability pipeline. +-- Control-flow reachability is a /sound over-approximation/ of +-- dataflow reachability under a sound call graph, which makes it +-- suitable as a shortlist \- not as a citation. Callers that need +-- to verify a specific sink is actually reached by attacker- +-- controlled input compose this query with a dataflow-path query +-- on top. +-- +-- Enumeration ( sink side free ) rather than verification ( sink +-- side bound ) is a deliberate shape choice : callers almost +-- always want /the set/ of reachable sinks per entry point, not a +-- per-site yes\/no. Per-site verification remains available via +-- 'ControlFlowPath'. +-- +-- The result payload carries per-kind sub-totals +-- ( 'SqlSinkKindCount' ) so callers can rank entry points by their +-- sink profile without iterating the matches list. +data ControlFlowReachableSqlSink + = ControlFlowReachableSqlSink + { + controlFlowReachableSqlSinkFrom :: Location, + controlFlowReachableSqlSinkLimitNumHops :: Word, + controlFlowReachableSqlSinkLimit :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Structural classifier for a single SQL sink call site. +-- +-- Same \"one concept, N structural paths\" tagged-union pattern as +-- 'AuthEvidence' : each constructor names a distinct sink shape a +-- KB-side recognizer can classify against. Framework-agnostic \- +-- the same two shapes appear across every ORM \/ DB library. The +-- concrete library name ( eg the resolved FQN of the sink call ) +-- is carried separately on each match as a plain string ; this +-- classifier abstracts over it. +-- +-- Current constructors : +-- +-- * @SqlPreparedStatement@ \- the sink parameterizes caller input +-- by construction ( bound parameters, ORM object-form APIs, ... ). +-- Injection-safe under the library's contract ; no additional +-- structural gate needed. +-- +-- * @SqlRaw@ \- the sink executes a caller-supplied SQL string. +-- Injection risk lives on the caller ; additional structural +-- gates ( eg proof that all interpolations are bound, or that +-- the string is a compile-time constant ) are needed to clear it. +-- +-- Adding a new shape is a pure leaf addition here + a matching +-- KB-side clause. No existing consumer needs to change. +data SqlSinkKind + = SqlPreparedStatement + | SqlRaw + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Per-kind sink count. Present in the enumeration payload as a +-- pre-aggregated ranking signal. Every constructor of 'SqlSinkKind' +-- is expected to appear in the payload's counts list ( zero-filled +-- when absent ) so callers can direct-lookup without existence +-- checks. +data SqlSinkKindCount + = SqlSinkKindCount + { + sqlSinkKindCountKind :: SqlSinkKind, + sqlSinkKindCountCount :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Result payload for 'ControlFlowReachableSqlSink'. +-- +-- @Total@ is the sum across all kinds ; @CountsByKind@ is the per-kind +-- breakdown ( a pre-aggregated ranking signal ) ; @Matches@ is the +-- flat list of individual sink call sites. Match ordering is +-- implementation-defined \- callers that need a specific ordering +-- should sort client-side on the fields exposed by +-- 'FoundControlFlowReachableSqlSinkMatch'. +data FoundControlFlowReachableSqlSink + = FoundControlFlowReachableSqlSink + { + foundControlFlowReachableSqlSinkTotal :: Word, + foundControlFlowReachableSqlSinkCountsByKind :: [ SqlSinkKindCount ], + foundControlFlowReachableSqlSinkMatches :: [ FoundControlFlowReachableSqlSinkMatch ] + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | A single reachable SQL sink match. +-- +-- Fields : +-- +-- * @Location@ \- the sink call site. Anchors downstream refinement +-- ( eg a structural clearance predicate or a dataflow query ). +-- +-- * @QualifiedName@ \- the fully qualified name of the sink callee +-- as a plain string ( a human-readable label for context ). Do +-- not dispatch on it ; dispatch on @Kind@ so the structural +-- classification stays authoritative. This is the naming +-- convention future kbapi additions should follow for FQN-shaped +-- string fields ; see the OWASP-IL talk notes for the +-- \"Qualified Names\" pedagogical framing. +-- +-- * @Kind@ \- structural classifier bound by the KB-side recognizer. +-- See 'SqlSinkKind' for the current catalog. +data FoundControlFlowReachableSqlSinkMatch + = FoundControlFlowReachableSqlSinkMatch + { + foundControlFlowReachableSqlSinkMatchLocation :: Location, + foundControlFlowReachableSqlSinkMatchQualifiedName :: String, + foundControlFlowReachableSqlSinkMatchKind :: SqlSinkKind + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Enumeration query \- file-action sinks control-flow-reachable +-- from an entry point. Symmetric to 'ControlFlowReachableSqlSink' ; +-- see that record for the coarse-to-fine framing. +data ControlFlowReachableFileActionSink + = ControlFlowReachableFileActionSink + { + controlFlowReachableFileActionSinkFrom :: Location, + controlFlowReachableFileActionSinkLimitNumHops :: Word, + controlFlowReachableFileActionSinkLimit :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Structural classifier for a single file-action sink call site. +-- +-- Same tagged-union pattern as 'SqlSinkKind' and 'AuthEvidence'. +-- Framework-agnostic \- the same shapes appear across every +-- filesystem API ( Node.js, Python, Go, Ruby, ... ). The concrete +-- library name is carried separately on each match as a plain +-- string ; this classifier abstracts over it. +-- +-- Current constructors : +-- +-- * @FileWrite@ \- content-writing sinks ( create \/ overwrite \/ +-- append file contents ). +-- +-- Reserved for future leaf additions : +-- +-- * @FileDelete@ \- removal sinks ( unlink \/ rmdir \/ recursive +-- remove ). +data FileActionKind + = FileWrite + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Per-kind file-action sink count. Symmetric to 'SqlSinkKindCount'. +data FileActionKindCount + = FileActionKindCount + { + fileActionKindCountKind :: FileActionKind, + fileActionKindCountCount :: Word + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | Result payload for 'ControlFlowReachableFileActionSink'. +-- Symmetric to 'FoundControlFlowReachableSqlSink' ; see that record +-- for the field semantics. +data FoundControlFlowReachableFileActionSink + = FoundControlFlowReachableFileActionSink + { + foundControlFlowReachableFileActionSinkTotal :: Word, + foundControlFlowReachableFileActionSinkCountsByKind :: [ FileActionKindCount ], + foundControlFlowReachableFileActionSinkMatches :: [ FoundControlFlowReachableFileActionSinkMatch ] + } + deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) + +-- | A single reachable file-action sink match. Symmetric to +-- 'FoundControlFlowReachableSqlSinkMatch' ; see that record for +-- the field semantics. +data FoundControlFlowReachableFileActionSinkMatch + = FoundControlFlowReachableFileActionSinkMatch + { + foundControlFlowReachableFileActionSinkMatchLocation :: Location, + foundControlFlowReachableFileActionSinkMatchQualifiedName :: String, + foundControlFlowReachableFileActionSinkMatchKind :: FileActionKind } deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) diff --git a/src/Kbapi.hs b/src/Kbapi.hs --- a/src/Kbapi.hs +++ b/src/Kbapi.hs @@ -57,10 +57,14 @@ | AuthenticatedHttpGetHandlerRequestObject Content.AuthenticatedHttpGetHandlerRequestObject | UnauthenticatedHttpPostHandlerRequestObject Content.UnauthenticatedHttpPostHandlerRequestObject | AuthenticatedHttpPostHandlerRequestObject Content.AuthenticatedHttpPostHandlerRequestObject + | UnauthenticatedHttpPutHandlerRequestObject Content.UnauthenticatedHttpPutHandlerRequestObject + | AuthenticatedHttpPutHandlerRequestObject Content.AuthenticatedHttpPutHandlerRequestObject | CommentsInFunction Content.CommentsInFunction | WriteContentToLocalFile Content.WriteContentToLocalFile | ControlFlowPath Content.ControlFlowPath | DataFlowPath Content.DataFlowPath + | ControlFlowReachableSqlSink Content.ControlFlowReachableSqlSink + | ControlFlowReachableFileActionSink Content.ControlFlowReachableFileActionSink deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON ) data QueryResult @@ -70,8 +74,12 @@ | FoundAuthenticatedHttpGetHandlerRequestObject Content.FoundAuthenticatedHttpGetHandlerRequestObject | FoundUnauthenticatedHttpPostHandlerRequestObject Content.FoundUnauthenticatedHttpPostHandlerRequestObject | FoundAuthenticatedHttpPostHandlerRequestObject Content.FoundAuthenticatedHttpPostHandlerRequestObject + | FoundUnauthenticatedHttpPutHandlerRequestObject Content.FoundUnauthenticatedHttpPutHandlerRequestObject + | FoundAuthenticatedHttpPutHandlerRequestObject Content.FoundAuthenticatedHttpPutHandlerRequestObject | FoundCommentsInFunction Content.FoundCommentsInFunction | FoundWriteContentToLocalFile Content.FoundWriteContentToLocalFile | FoundControlFlowPath Content.FoundControlFlowPath | FoundDataFlowPath Content.FoundDataFlowPath + | FoundControlFlowReachableSqlSink Content.FoundControlFlowReachableSqlSink + | FoundControlFlowReachableFileActionSink Content.FoundControlFlowReachableFileActionSink deriving ( Show, Eq, Ord, Generic, ToJSON, FromJSON )