/**

* Provides classes modeling security-relevant aspects of the `twisted` PyPI package.

* See https://twistedmatrix.com/.

*/

private import python

private import semmle.python.dataflow.new.DataFlow

private import semmle.python.dataflow.new.RemoteFlowSources

private import semmle.python.dataflow.new.TaintTracking

private import semmle.python.Concepts

private import semmle.python.ApiGraphs

private import semmle.python.frameworks.internal.InstanceTaintStepsHelper

/**

* Provides models for the `twisted` PyPI package.

* See https://twistedmatrix.com/.

*/

private module Twisted {

// ---------------------------------------------------------------------------

// request handler modeling

// ---------------------------------------------------------------------------

/**

* A class that is a subclass of `twisted.web.resource.Resource`, thereby

* being able to handle HTTP requests.

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.resource.Resource.html

*/

class TwistedResourceSubclass extends Class {

TwistedResourceSubclass() {

this.getParent() =

API::moduleImport("twisted")

.getMember("web")

.getMember("resource")

.getMember("Resource")

.getASubclass*()

.asSource()

.asExpr()

}

/** Gets a function that could handle incoming requests, if any. */

Function getARequestHandler() {

// TODO: This doesn't handle attribute assignment. Should be OK, but analysis is not as complete as with

// points-to and `.lookup`, which would handle `post = my_post_handler` inside class def

result = this.getAMethod() and

exists(getRequestParamIndex(result.getName()))

}

}

/**

* Gets the index the request parameter is supposed to be at for the method named

* `methodName` in a `twisted.web.resource.Resource` subclass.

*/

bindingset[methodName]

private int getRequestParamIndex(string methodName) {

methodName.matches("render_%") and result = 1

or

methodName in ["render", "listDynamicEntities", "getChildForRequest"] and result = 1

or

methodName = ["getDynamicEntity", "getChild", "getChildWithDefault"] and result = 2

}

/** A method that handles incoming requests, on a `twisted.web.resource.Resource` subclass. */

class TwistedResourceRequestHandler extends Http::Server::RequestHandler::Range {

TwistedResourceRequestHandler() { this = any(TwistedResourceSubclass cls).getARequestHandler() }

Parameter getRequestParameter() { result = this.getArg(getRequestParamIndex(this.getName())) }

override Parameter getARoutedParameter() { none() }

override string getFramework() { result = "twisted" }

}

/**

* A "render" method on a `twisted.web.resource.Resource` subclass, whose return value

* is written as the body of the HTTP response.

*/

class TwistedResourceRenderMethod extends TwistedResourceRequestHandler {

TwistedResourceRenderMethod() {

this.getName() = "render" or this.getName().matches("render_%")

}

}

// ---------------------------------------------------------------------------

// request modeling

// ---------------------------------------------------------------------------

/**

* Provides models for the `twisted.web.server.Request` class

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.server.Request.html

*/

module Request {

/**

* A source of instances of `twisted.web.server.Request`, extend this class to model new instances.

*

* This can include instantiations of the class, return values from function

* calls, or a special parameter that will be set when functions are called by an external

* library.

*

* Use `Request::instance()` predicate to get

* references to instances of `twisted.web.server.Request`.

*/

abstract class InstanceSource extends DataFlow::LocalSourceNode { }

/** Gets a reference to an instance of `twisted.web.server.Request`. */

private DataFlow::TypeTrackingNode instance(DataFlow::TypeTracker t) {

t.start() and

result instanceof InstanceSource

or

exists(DataFlow::TypeTracker t2 | result = instance(t2).track(t2, t))

}

/** Gets a reference to an instance of `twisted.web.server.Request`. */

DataFlow::Node instance() { instance(DataFlow::TypeTracker::end()).flowsTo(result) }

/**

* Taint propagation for `twisted.web.server.Request`.

*/

private class InstanceTaintSteps extends InstanceTaintStepsHelper {

InstanceTaintSteps() { this = "twisted.web.server.Request" }

override DataFlow::Node getInstance() { result = instance() }

override string getAttributeName() {

result in [

"uri", "path", "prepath", "postpath", "content", "args", "received_cookies",

"requestHeaders", "user", "password", "host"

]

}

override string getMethodName() {

result in [

"getCookie", "getHeader", "getAllHeaders", "getUser", "getPassword", "getHost",

"getRequestHostname"

]

}

override string getAsyncMethodName() { none() }

}

}

/**

* A parameter that will receive a `twisted.web.server.Request` instance,

* when a twisted request handler is called.

*/

class TwistedResourceRequestHandlerRequestParam extends RemoteFlowSource::Range,

Request::InstanceSource, DataFlow::ParameterNode

{

TwistedResourceRequestHandlerRequestParam() {

this.getParameter() = any(TwistedResourceRequestHandler handler).getRequestParameter()

}

override string getSourceType() { result = "twisted.web.server.Request" }

}

/**

* A parameter of a request handler method (on a `twisted.web.resource.Resource` subclass)

* that is also given remote user input. (a bit like RoutedParameter).

*/

class TwistedResourceRequestHandlerExtraSources extends RemoteFlowSource::Range,

DataFlow::ParameterNode

{

TwistedResourceRequestHandlerExtraSources() {

exists(TwistedResourceRequestHandler func, int i |

func.getName() in ["getChild", "getChildWithDefault"] and i = 1

or

func.getName() = "getDynamicEntity" and i = 1

|

this.getParameter() = func.getArg(i)

)

}

override string getSourceType() { result = "twisted Resource method extra parameter" }

}

// ---------------------------------------------------------------------------

// response modeling

// ---------------------------------------------------------------------------

/**

* Implicit response from returns of render methods.

*/

private class TwistedResourceRenderMethodReturn extends Http::Server::HttpResponse::Range,

DataFlow::CfgNode

{

TwistedResourceRenderMethodReturn() {

this.asCfgNode() = any(TwistedResourceRenderMethod meth).getAReturnValueFlowNode()

}

override DataFlow::Node getBody() { result = this }

override DataFlow::Node getMimetypeOrContentTypeArg() { none() }

override string getMimetypeDefault() { result = "text/html" }

}

/**

* A call to the `twisted.web.server.Request.write` function.

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.server.Request.html#write

*/

class TwistedRequestWriteCall extends Http::Server::HttpResponse::Range, DataFlow::MethodCallNode {

TwistedRequestWriteCall() { this.calls(Request::instance(), "write") }

override DataFlow::Node getBody() {

result.asCfgNode() in [node.getArg(0), node.getArgByName("data")]

}

override DataFlow::Node getMimetypeOrContentTypeArg() { none() }

override string getMimetypeDefault() { result = "text/html" }

}

/**

* A call to the `redirect` function on a twisted request.

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.http.Request.html#redirect

*/

class TwistedRequestRedirectCall extends Http::Server::HttpRedirectResponse::Range,

DataFlow::MethodCallNode

{

TwistedRequestRedirectCall() { this.calls(Request::instance(), "redirect") }

override DataFlow::Node getBody() { none() }

override DataFlow::Node getRedirectLocation() {

result.asCfgNode() in [node.getArg(0), node.getArgByName("url")]

}

override DataFlow::Node getMimetypeOrContentTypeArg() { none() }

override string getMimetypeDefault() { result = "text/html" }

}

/**

* A call to the `addCookie` function on a twisted request.

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.http.Request.html#addCookie

*/

class TwistedRequestAddCookieCall extends Http::Server::SetCookieCall, DataFlow::MethodCallNode {

TwistedRequestAddCookieCall() { this.calls(Twisted::Request::instance(), "addCookie") }

override DataFlow::Node getHeaderArg() { none() }

override DataFlow::Node getNameArg() { result in [this.getArg(0), this.getArgByName("k")] }

override DataFlow::Node getValueArg() { result in [this.getArg(1), this.getArgByName("v")] }

}

/**

* A call to `append` on the `cookies` attribute of a twisted request.

*

* See https://twistedmatrix.com/documents/21.2.0/api/twisted.web.http.Request.html#cookies

*/

class TwistedRequestCookiesAppendCall extends Http::Server::CookieWrite::Range,

DataFlow::MethodCallNode

{

TwistedRequestCookiesAppendCall() {

exists(DataFlow::AttrRead cookiesLookup |

cookiesLookup.getObject() = Twisted::Request::instance() and

cookiesLookup.getAttributeName() = "cookies" and

this.calls(cookiesLookup, "append")

)

}

override DataFlow::Node getHeaderArg() { result = this.getArg(0) }

override DataFlow::Node getNameArg() { none() }

override DataFlow::Node getValueArg() { none() }

}

}