{
    "info": {
        "author": "inovex GmbH",
        "author_email": "list-ito+illuminatio@inovex.de",
        "bugtrack_url": null,
        "classifiers": [
            "Development Status :: 4 - Beta",
            "Programming Language :: Python"
        ],
        "description": "# Illuminatio - The kubernetes network policy validator\n\n[![Build Status](https://travis-ci.org/inovex/illuminatio.svg?branch=master)](https://travis-ci.org/inovex/illuminatio)\n\n![alt text](/logo/logo_small.png)\n\nIlluminatio is a tool for automatically testing kubernetes network policies.\nSimply execute `illuminatio clean run`\nand Illuminatio will scan your kubernetes cluster for network policies, build test cases accordingly and execute them\nto determine if the policies are in effect.\n\nAn overview of the concept is visualized in [the concept doc](docs/concept.md).\n\n## Getting started\n\nFollow these instructions to get Illuminatio up and running.\n\n## Prerequisites\n\n- Python 3\n- Pip 3\n\n## Installation\n\nwith pip:\n\n```bash\npip3 install illuminatio\n```\n\nor directly from the repository:\n\n```bash\ngit clone https://github.com/inovex/illuminatio\ncd illuminatio\npython3 setup.py install\ncd ..\n```\n\n## Example Usage\n\nCreate a Deployment to test with:\n\n```bash\nkubectl create deployment web --image=nginx\nkubectl expose deployment web --port 80 --target-port 80\n```\n\nDefine and create a NetworkPolicy for your Deployment:\n\n```bash\ncat <<EOF | kubectl create -f -\nkind: NetworkPolicy\napiVersion: networking.k8s.io/v1\nmetadata:\n  name: web-deny-all\nspec:\n  podSelector:\n    matchLabels:\n      app: web\n  ingress: []\nEOF\n```\n\nTest your newly created NetworkPolicy:\n\n```bash\nilluminatio clean run\nStarting cleaning resources with policies ['on-request', 'always']\nDeleting namespaces [] with cleanup policy on-request\nDeleting namespaces [] with cleanup policy always\nDeleting DSs in default with cleanup policy on-request\nDeleting pods in default with cleanup policy on-request\nDeleting svcs in default with cleanup policy on-request\nDeleting CfgMaps in default with cleanup policy on-request\nDeleting CRBs  with cleanup policy on-request globally\nDeleting SAs in default with cleanup policy on-request\nDeleting DSs in default with cleanup policy always\nDeleting pods in default with cleanup policy always\nDeleting svcs in default with cleanup policy always\nDeleting CfgMaps in default with cleanup policy always\nDeleting CRBs  with cleanup policy always globally\nDeleting SAs in default with cleanup policy always\nFinished cleanUp\n\nStarting test generation and run.\nGot cases: [NetworkTestCase(from=ClusterHost(namespace=default, podLabels={'app': 'web'}), to=ClusterHost(namespace=default, podLabels={'app': 'web'}), port=-*)]\nGenerated 1 cases in 0.0701 seconds\nFROM             TO               PORT\ndefault:app=web  default:app=web  -*\n\nUsing existing cluster role\nCreating cluster role binding\nTestResults: {'default:app=web': {'default:app=web': {'-*': {'success': True}}}}\nFinished running 1 tests in 18.7413 seconds\nFROM             TO               PORT  RESULT\ndefault:app=web  default:app=web  -*    success\n```\n\nThe `clean` keyword assures that illuminatio clears all potentially existing resources created in past illuminatio runs to prevent potential issues, however no user generated resources are affected.\n\n*PLEASE NOTE* that currently each new run requires a clean, as the runners do not continuously look for new cases.\n\nFor the case that you really want to keep the generated resources you are free to omit the `clean` keyword.\n\nIf you are done testing you might want to easily delete all resources created by illuminatio:\n\n```bash\nilluminatio clean\n```\n\nTo preview generated test cases without running tests use `illuminatio run`'s `--dry` option:\n\n```bash\nilluminatio run --dry\nStarting test generation and run.\nGot cases: [NetworkTestCase(from=ClusterHost(namespace=default, podLabels={'app': 'web'}), to=ClusterHost(namespace=default, podLabels={'app': 'web'}), port=-*)]\nGenerated 1 cases in 0.0902 seconds\nFROM             TO               PORT\ndefault:app=web  default:app=web  -*\n\nSkipping test execution as --dry was set\n```\n\nAll options and further information can be found using the `--help` flag on any level:\n\n```bash\nilluminatio --help\n```\n\n```Bash\nUsage: illuminatio [OPTIONS] COMMAND1 [ARGS]... [COMMAND2 [ARGS]...]...\n\nOptions:\n  -v, --verbosity LVL  Either CRITICAL, ERROR, WARNING, INFO or DEBUG\n  --incluster\n  --help               Show this message and exit.\n\nCommands:\n  clean\n  run\n```\n\n## Docker Usage\n\nInstead of installing the `illumnatio` cli on your machine you can also use our Docker image.\nYou will need to provide the `kubeconfig` to the container and probably some certificates:\n\n```bash\ndocker run -ti -v ~/.kube:/home/illuminatio/.kube:ro inovex/illuminatio clean run\n```\n\n### Minikube\n\nMinikube will store the certificates in the users home so we need to pass these to the container:\n\n```bash\ndocker run -ti -v \"${HOME}/.minikube\":\"${HOME}/.minikube\" -v \"${HOME}/.kube:\"/home/illuminatio/.kube:ro inovex/illuminatio clean run\n```\n\nIf the minikube VM is not reachable from your container try to pass the `--net=host` flag to the docker run command.\n\n## Compatibility\n\nilluminatio 1.1 was tested using:\n\n- python 3.5.2\n- pip 19.2.1\n\nilluminatio 1.1 is confirmed to be working properly with the following kubernetes environments:\n\n- minikube v0.34.1, kubernetes v1.13.3\n- Google Kubernetes Engine, v1.12.8-gke.10\n- kubeadm 1.15.0-00, kubernetes v1.15.2\n\n### PodSecurityPolicy\n\nIf your cluster has the [PodSecurityPolicy](https://kubernetes.io/docs/reference/access-authn-authz/admission-controllers/#podsecuritypolicy) Admission Controller you must ensure that the illuminatio runner has the following rights to be created:\n\n- Wants to run as root\n- Needs the `SYS_ADMIN` capability\n- Needs `allowPrivilegeEscalation: true`\n- Needs access to the `hostPath` for the network namespaces and the cri socket\n\nA `PodSecurityPolicy` granting these privileges needs to be bound to the `illuminatio-runner` `ServiceAccount` in the `illuminatio` namespace.\nFor more details look at the [illuminatio DaemonSet](src/illuminatio/manifests/containerd-daemonset.yaml)\n\n## References\n\nThe logo was created by Pia Blum.\n\nExample Network Policies are inspired by\n[kubernetes-network-policy-recipes](https://github.com/ahmetb/kubernetes-network-policy-recipes)\n\nPresentation from [ContainerDays 2019](https://www.youtube.com/watch?v=eEkTvAez8HA&list=PLHhKcdBlprMdg-fwPD1b3IjBRR_Ga09H0&index=36), [slides](https://www.inovex.de/de/content-pool/vortraege/network-policies)\n\n## Contributing\n\nWe are happy to read your [issues](https://github.com/inovex/illuminatio/issues) and accept your [Pull Requests.](https://github.com/inovex/illuminatio/compare)\nThis project uses the [standard github flow](https://help.github.com/en/articles/creating-a-pull-request-from-a-fork).\nFor more information on developing illuminatio refer to [the development docs](docs/developing.md).\n\n## License\n\nThis project excluding the logo is licensed under the terms of the Apache 2.0 license.\nThe logo is licensed under the terms of the CC BY-NC-ND 4.0 license.\n\n\n",
        "description_content_type": "text/markdown",
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/inovex/illuminatio",
        "keywords": "",
        "license": "apache",
        "maintainer": "",
        "maintainer_email": "",
        "name": "illuminatio",
        "package_url": "https://pypi.org/project/illuminatio/",
        "platform": "any",
        "project_url": "https://pypi.org/project/illuminatio/",
        "project_urls": {
            "Homepage": "https://github.com/inovex/illuminatio"
        },
        "release_url": "https://pypi.org/project/illuminatio/1.3/",
        "requires_dist": [
            "requests",
            "google-auth",
            "python-dateutil",
            "pyyaml",
            "oauthlib",
            "kubernetes",
            "click",
            "click-log",
            "docker",
            "nsenter",
            "attrs",
            "pluggy",
            "pytest",
            "urllib3",
            "setuptools"
        ],
        "requires_python": "",
        "summary": "The kubernetes network policy validator.",
        "version": "1.3"
    },
    "last_serial": 5814076,
    "releases": {
        "1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "5c5af93ff2ee36a3fddbf8e57bd16155",
                    "sha256": "2142496f38be4ff947474b34114a11a0d72aafd299d7d6d4abb4da0052d90b45"
                },
                "downloads": -1,
                "filename": "illuminatio-1.0-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "5c5af93ff2ee36a3fddbf8e57bd16155",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 37510,
                "upload_time": "2019-06-26T15:22:57",
                "url": "https://files.pythonhosted.org/packages/a1/93/8b547b4b43e3ce5b4e66e846eb922d91901c9f254fde4640c74f753d3957/illuminatio-1.0-py2.py3-none-any.whl"
            }
        ],
        "1.1": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "805e8638cb9f99fe4694c02b4592265d",
                    "sha256": "98cf2fae69b25303d96fb18c5229553ee8cbf2ba9a03ab2cb0d054af24b14b44"
                },
                "downloads": -1,
                "filename": "illuminatio-1.1-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "805e8638cb9f99fe4694c02b4592265d",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 36375,
                "upload_time": "2019-08-12T12:58:17",
                "url": "https://files.pythonhosted.org/packages/5e/8f/7b5295fe4ffd0541eac49f91b0f859a679f5dee00accc98a6e538f9fc089/illuminatio-1.1-py2.py3-none-any.whl"
            }
        ],
        "1.2": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "8c113e4ae69a840ac3c3ae48b0bc7557",
                    "sha256": "1fbcfedda002d6e066fc8431adb65efa9e000c8f9bec2500457d51bfec582e7b"
                },
                "downloads": -1,
                "filename": "illuminatio-1.2-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "8c113e4ae69a840ac3c3ae48b0bc7557",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 36276,
                "upload_time": "2019-09-11T06:27:46",
                "url": "https://files.pythonhosted.org/packages/4b/b4/bd18832c39b4703cf62139461f51e9460f793edd7339c95884f4e97777af/illuminatio-1.2-py2.py3-none-any.whl"
            }
        ],
        "1.3": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "e85744e5c985bfd10257906163862c57",
                    "sha256": "b901a00a99c2d41d548d2b49b34792b4d1f3c6acf420db2e85fe59b2f8365bf5"
                },
                "downloads": -1,
                "filename": "illuminatio-1.3-py2.py3-none-any.whl",
                "has_sig": false,
                "md5_digest": "e85744e5c985bfd10257906163862c57",
                "packagetype": "bdist_wheel",
                "python_version": "py2.py3",
                "requires_python": null,
                "size": 36626,
                "upload_time": "2019-09-11T10:02:44",
                "url": "https://files.pythonhosted.org/packages/28/b8/f8e149c5145ebbb74fb7b1dbf3c4889c86ed562718c52a7e780aff76f847/illuminatio-1.3-py2.py3-none-any.whl"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "e85744e5c985bfd10257906163862c57",
                "sha256": "b901a00a99c2d41d548d2b49b34792b4d1f3c6acf420db2e85fe59b2f8365bf5"
            },
            "downloads": -1,
            "filename": "illuminatio-1.3-py2.py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "e85744e5c985bfd10257906163862c57",
            "packagetype": "bdist_wheel",
            "python_version": "py2.py3",
            "requires_python": null,
            "size": 36626,
            "upload_time": "2019-09-11T10:02:44",
            "url": "https://files.pythonhosted.org/packages/28/b8/f8e149c5145ebbb74fb7b1dbf3c4889c86ed562718c52a7e780aff76f847/illuminatio-1.3-py2.py3-none-any.whl"
        }
    ]
}