abhinavsingh
diff --git a/‎.github/workflows/codeql-analysis.yml‎
Lines changed: 71 additions & 0 deletions b/‎.github/workflows/codeql-analysis.yml‎
Lines changed: 71 additions & 0 deletions
diff --git a/‎Dockerfile‎
Lines changed: 1 addition & 1 deletion b/‎Dockerfile‎
Lines changed: 1 addition & 1 deletion
diff --git a/‎Makefile‎
Lines changed: 20 additions & 3 deletions b/‎Makefile‎
Lines changed: 20 additions & 3 deletions
diff --git a/‎README.md‎
Lines changed: 101 additions & 1 deletion b/‎README.md‎
Lines changed: 101 additions & 1 deletion
diff --git a/‎SECURITY.md‎
Lines changed: 16 additions & 0 deletions b/‎SECURITY.md‎
Lines changed: 16 additions & 0 deletions
diff --git a/‎tests/codecov.yml‎ renamed to ‎codecov.yml‎ b/‎tests/codecov.yml‎ renamed to ‎codecov.yml‎
@@ -0,0 +1,71 @@
+# For most projects, this workflow file will not need changing; you simply need
+# to commit it to your repository.
+#
+# You may wish to alter this file to override the set of languages analyzed,
+# or to provide custom queries or build logic.
+name: "CodeQL"
+
+on:
+  push:
+    branches: [develop, master]
+  pull_request:
+    # The branches below must be a subset of the branches above
+    branches: [develop]
+  schedule:
+    - cron: '0 14 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        # Override automatic language detection by changing the below list
+        # Supported options are ['csharp', 'cpp', 'go', 'java', 'javascript', 'python']
+        language: ['python', 'javascript']
+        # Learn more...
+        # https://docs.github.com/en/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#overriding-automatic-language-detection
+
+    steps:
+    - name: Checkout repository
+      uses: actions/checkout@v2
+      with:
+        # We must fetch at least the immediate parents so that if this is
+        # a pull request then we can checkout the head.
+        fetch-depth: 2
+
+    # If this run was triggered by a pull request event, then checkout
+    # the head of the pull request instead of the merge commit.
+    - run: git checkout HEAD^2
+      if: ${{ github.event_name == 'pull_request' }}
+
+    # Initializes the CodeQL tools for scanning.
+    - name: Initialize CodeQL
+      uses: github/codeql-action/init@v1
+      with:
+        languages: ${{ matrix.language }}
+        # If you wish to specify custom queries, you can do so here or in a config file.
+        # By default, queries listed here will override any specified in a config file. 
+        # Prefix the list here with "+" to use these queries and those in the config file.
+        # queries: ./path/to/local/query, your-org/your-repo/queries@main
+
+    # Autobuild attempts to build any compiled languages  (C/C++, C#, or Java).
+    # If this step fails, then you should remove it and run the build manually (see below)
+    # - name: Autobuild
+    #   uses: github/codeql-action/autobuild@v1
+
+    # ℹ️ Command-line programs to run using the OS shell.
+    # 📚 https://git.io/JvXDl
+
+    # ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
+    #    and modify them (or add more) to build your code if your project
+    #    uses a compiled language
+
+    #- run: |
+    #   make bootstrap
+    #   make release
+
+    - name: Perform CodeQL Analysis
+      uses: github/codeql-action/analyze@v1
@@ -7,7 +7,7 @@ COPY README.md /app/
 COPY proxy/ /app/proxy/
 WORKDIR /app
 RUN pip install --upgrade pip && \
-    pip install --install-option="--prefix=/deps" .
+    pip install --prefix=/deps .
 
 FROM base
 
 
@@ -8,6 +8,8 @@ IMAGE_TAG := $(NS)/$(IMAGE_NAME):$(VERSION)
 
 HTTPS_KEY_FILE_PATH := https-key.pem
 HTTPS_CERT_FILE_PATH := https-cert.pem
+HTTPS_CSR_FILE_PATH := https-csr.pem
+HTTPS_SIGNED_CERT_FILE_PATH := https-signed-cert.pem
 
 CA_KEY_FILE_PATH := ca-key.pem
 CA_CERT_FILE_PATH := ca-cert.pem
@@ -25,6 +27,7 @@ devtools:
 	pushd dashboard && npm run devtools && popd
 
 autopep8:
+	autopep8 --recursive --in-place --aggressive examples
 	autopep8 --recursive --in-place --aggressive proxy
 	autopep8 --recursive --in-place --aggressive tests
 	autopep8 --recursive --in-place --aggressive setup.py
@@ -40,6 +43,20 @@ https-certificates:
 		--private-key-path $(HTTPS_KEY_FILE_PATH) \
 		--public-key-path $(HTTPS_CERT_FILE_PATH)
 
+sign-https-certificates:
+	# Generate CSR request
+	python -m proxy.common.pki gen_csr \
+		--csr-path $(HTTPS_CSR_FILE_PATH) \
+		--private-key-path $(HTTPS_KEY_FILE_PATH) \
+		--public-key-path $(HTTPS_CERT_FILE_PATH)
+	# Sign CSR with CA
+	python -m proxy.common.pki sign_csr \
+		--csr-path $(HTTPS_CSR_FILE_PATH) \
+		--crt-path $(HTTPS_SIGNED_CERT_FILE_PATH) \
+		--hostname example.com \
+		--private-key-path $(CA_KEY_FILE_PATH) \
+		--public-key-path $(CA_CERT_FILE_PATH)
+
 ca-certificates:
 	# Generate CA key
 	python -m proxy.common.pki gen_private_key \
@@ -73,8 +90,8 @@ lib-clean:
 	rm -rf .hypothesis
 
 lib-lint:
-	flake8 --ignore=W504 --max-line-length=127 --max-complexity=19 proxy/ tests/ setup.py
-	mypy --strict --ignore-missing-imports proxy/ tests/ setup.py
+	flake8 --ignore=W504 --max-line-length=127 --max-complexity=19 examples/ proxy/ tests/ setup.py
+	mypy --strict --ignore-missing-imports examples/ proxy/ tests/ setup.py
 
 lib-test: lib-clean lib-version lib-lint
 	pytest -v tests/
@@ -93,7 +110,7 @@ lib-coverage:
 	open htmlcov/index.html
 
 lib-profile:
-	sudo py-spy -F -f profile.svg -d 3600 proxy.py
+	sudo py-spy record -o profile.svg -t -F -s -- python -m proxy
 
 dashboard:
 	pushd dashboard && npm run build && popd
 
@@ -57,6 +57,8 @@ Table of Contents
         * [Cache Responses Plugin](#cacheresponsesplugin)
         * [Man-In-The-Middle Plugin](#maninthemiddleplugin)
         * [Proxy Pool Plugin](#proxypoolplugin)
+        * [FilterByClientIpPlugin](#filterbyclientipplugin)
+        * [ModifyChunkResponsePlugin](#modifychunkresponseplugin)
     * [HTTP Web Server Plugins](#http-web-server-plugins)
         * [Reverse Proxy](#reverse-proxy)
         * [Web Server Route](#web-server-route)
@@ -70,6 +72,7 @@ Table of Contents
 * [Embed proxy.py](#embed-proxypy)
     * [Blocking Mode](#blocking-mode)
     * [Non-blocking Mode](#non-blocking-mode)
+    * [Loading Plugins](#loading-plugins)
 * [Unit testing with proxy.py](#unit-testing-with-proxypy)
     * [proxy.TestCase](#proxytestcase)
     * [Override Startup Flags](#override-startup-flags)
@@ -669,6 +672,57 @@ Make a curl request via `8899` proxy:
 Verify that `8899` proxy forwards requests to upstream proxies
 by checking respective logs.
 
+### FilterByClientIpPlugin
+
+Reject traffic from specific IP addresses.  By default this
+plugin blocks traffic from `127.0.0.1` and `::1`.
+
+Start `proxy.py` as:
+
+```bash
+❯ proxy \
+    --plugins proxy.plugin.FilterByClientIpPlugin
+```
+
+Send a request using `curl -v -x localhost:8899 http://google.com`:
+
+```bash
+... [redacted] ...
+> Proxy-Connection: Keep-Alive
+>
+< HTTP/1.1 418 I'm a tea pot
+< Connection: close
+<
+* Closing connection 0
+```
+
+Modify plugin to your taste e.g. Allow specific IP addresses only.
+
+### ModifyChunkResponsePlugin
+
+This plugin demonstrate how to modify chunked encoded responses.  In able to do so, this plugin uses `proxy.py` core to parse the chunked encoded response.  Then we reconstruct the response using custom hardcoded chunks, ignoring original chunks received from upstream server.
+
+Start `proxy.py` as:
+
+```bash
+❯ proxy \
+    --plugins proxy.plugin.ModifyChunkResponsePlugin
+```
+
+Verify using `curl -v -x localhost:8899 http://httpbin.org/stream/5`:
+
+```bash
+... [redacted] ...
+modify
+chunk
+response
+plugin
+* Connection #0 to host localhost left intact
+* Closing connection 0
+```
+
+Modify `ModifyChunkResponsePlugin` to your taste. Example, instead of sending hardcoded chunks, parse and modify the original `JSON` chunks received from the upstream server.
+
 ## HTTP Web Server Plugins
 
 ### Reverse Proxy
@@ -774,6 +828,22 @@ Verify using `curl -x https://localhost:8899 --proxy-cacert https-cert.pem https
 }
 ```
 
+If you want to avoid passing `--proxy-cacert` flag, also consider signing generated SSL certificates.  Example:
+
+First, generate CA certificates:
+
+```bash
+make ca-certificates
+```
+
+Then, sign SSL certificate:
+
+```bash
+make sign-https-certificates
+```
+
+Now restart the server with `--cert-file https-signed-cert.pem` flag.  Note that you must also trust generated `ca-cert.pem` in your system keychain.
+
 TLS Interception
 =================
 
@@ -1103,6 +1173,36 @@ Note that:
    input arguments e.g. `start(['--port', '8899'])` or
    by using passing flags as kwargs e.g. `start(port=8899)`.
 
+## Loading Plugins
+
+You can, of course, list plugins to load in the input arguments list of `proxy.main`, `proxy.start` or the `Proxy` constructor. Use the `--plugins` flag as when starting from command line:
+
+```python
+import proxy
+
+if __name__ == '__main__':
+  proxy.main([
+    '--plugins', 'proxy.plugin.CacheResponsesPlugin',
+  ])
+```
+
+However, for simplicity you can pass the list of plugins to load as a keyword argument to `proxy.main`, `proxy.start` or the `Proxy` constructor:
+
+```python
+import proxy
+from proxy.plugin import FilterByUpstreamHostPlugin
+
+if __name__ == '__main__':
+  proxy.main([], plugins=[
+    b'proxy.plugin.CacheResponsesPlugin',
+    FilterByUpstreamHostPlugin,
+  ])
+```
+
+Note that it supports:
+1. The fully-qualified name of a class as `bytes`
+2. Any `type` instance for a Proxy.py plugin class. This is espacially useful for custom plugins defined locally.
+
 Unit testing with proxy.py
 ==========================
 
@@ -1603,7 +1703,7 @@ usage: proxy [-h] [--backlog BACKLOG] [--basic-auth BASIC_AUTH]
              [--static-server-dir STATIC_SERVER_DIR] [--threadless]
              [--timeout TIMEOUT] [--version]
 
-proxy.py v2.2.0
+proxy.py v2.3.0
 
 optional arguments:
   -h, --help            show this help message and exit
 
@@ -0,0 +1,16 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 2.x     | :white_check_mark: |
+| < 2.x   | :x:                |
+
+## Reporting a Vulnerability
+
+Follow these steps:
+
+1. Start by [emailing developers](mailto:[email protected])
+2. If unresponsive, [create a public issue](https://github.com/abhinavsingh/proxy.py/issues/new/choose)
+3. [Pull requests](https://github.com/abhinavsingh/proxy.py/pulls) are always welcome