{"id":20244522,"url":"https://github.com/retailmenotsandbox/sgtools","last_synced_at":"2025-03-03T15:24:24.149Z","repository":{"id":15939126,"uuid":"18681349","full_name":"RetailMeNotSandbox/sgtools","owner":"RetailMeNotSandbox","description":"Standard UNIX tools for manipulating AWS security group rules","archived":false,"fork":false,"pushed_at":"2014-04-11T19:32:53.000Z","size":144,"stargazers_count":1,"open_issues_count":1,"forks_count":1,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-02-18T21:40:17.281Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RetailMeNotSandbox.png","metadata":{"files":{"readme":"README.rst","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-11T16:44:07.000Z","updated_at":"2017-04-19T04:20:13.000Z","dependencies_parsed_at":"2022-08-30T14:51:26.125Z","dependency_job_id":null,"html_url":"https://github.com/RetailMeNotSandbox/sgtools","commit_stats":null,"previous_names":["retailmenot/sgtools"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetailMeNotSandbox%2Fsgtools","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetailMeNotSandbox%2Fsgtools/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetailMeNotSandbox%2Fsgtools/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RetailMeNotSandbox%2Fsgtools/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RetailMeNotSandbox","download_url":"https://codeload.github.com/RetailMeNotSandbox/sgtools/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241688075,"owners_count":20003393,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-11-14T09:15:47.053Z","updated_at":"2025-03-03T15:24:24.128Z","avatar_url":"https://github.com/RetailMeNotSandbox.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\nSecurity Group Management Rule Management in sgtools\n%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%\n\nConcepts\n********\n\nSecurity Groups rules in AWS have four basic components. In sgtools and this\ndocumentation, we refer to them as follows:\n\n* A *direction*, \"in\" (ingress) or \"out\" (egress)\n* An *owner*, the group to whom the rule belongs\n* An *other*, the subject of the rule, which may be a security group or CIDR\n* A *portspec*, consisting of an IP protocol, low port, and high port\n\nIncluded Tools\n**************\n\nsgtools includes two tools for managing security group rules: ``sgtables`` and\n``sgmanager``.\n\n``sgmanager`` is a higher-level tool used for managing more human-friendly rule\nrepresentations. ``sgmanager`` depends on ``sgtables`` to make changes in AWS.\n\n``stgables`` is a low-level (*raw*) rule processor. It consumes and generates\nbasic rule definitions, and is capable of modifying rulesets in AWS.\n\nThese tools only manage security group *rules*. They do not create or remove\nthe groups themselves.\n\nUsing ``sgmanager``\n*******************\n\n.. hint::\n    You can type ``sgmanager --help`` for detailed help about the ``sgmanager`` CLI.\n\nThere are currently three ``sgmanager`` subcommands:\n\n* *groupdefs*, a tool for extracting group definitions in the ``sgmanager``\n* format *render*, which accepts one or more configuration files and renders\n  them to raw rules suitable for consumption by ``sgtables``\n* *reverse*, which can help you convert ``sgtables`` output to a set of rules\n\nWhen using ``sgmanager``, *vars_files* are files in the ``sgmanager``\nconfiguration format as outlined below. *input_files* refer to files containing\nraw rules as output by ``sgtables``.\n\n.. hint::\n    ``sgmanager`` configurations can be broken into several files for\n    flexibility. Consider storing accounts, CIDRs, and portspecs separately\n    from group definitions and rules.\n\n``sgmanager`` Configuration\n---------------------------\n\nThere are four entity types that can be defined in an sgmanager configuration:\n\n* Rule - represents a single IpPermission on a SecurityGroup\n* SecurityGroup - represents a single AWS SecurityGroup\n* Cidr - An IPv4 CIDR address/mask\n* Account - an AWS account\n\n\nThe syntax of an sgmanager configuration is::\n\n    \u003crule\u003e          ::= \"rule \" \u003cDirection\u003e \" \" \u003cSecurityGroup:NAME\u003e \" \" ( \u003cSecurityGroup:NAME\u003e | \u003cCidr:NAME\u003e ) \" \" \u003cPortSpec:NAME\u003e\n\n    \u003cSecurityGroup\u003e ::= \"sg \" NAME \" \" SG_ID\n\n    \u003cCidr\u003e          ::= \"cidr \" NAME \" \" IPADDR \"/\" INT_MASK\n    \n    \u003cAccount\u003e       ::= \"acct \" NAME \" \" ACCOUNT_ID\n\n    \u003cPortSpec\u003e      ::= \"proto \" NAME \" \" \u003cProtocol\u003e \" \" \u003cLport\u003e \" \" \u003cHport\u003e\n    \u003cProtocol\u003e      ::= ( \"icmp\" | \"tcp\" | \"udp\" | -1 | 0 | POSITIVE_INTEGER )\n    \u003cLport\u003e         ::= -1 | 0 | POSITIVE_INTEGER\n    \u003cHport\u003e         ::= -1 | 0 | POSITIVE_INTEGER\n\nWhere:\n\n* ``SG_ID`` is an AWS security group id\n* ``IPADDR`` is an IPv4 address\n* ``INT_MASK`` is an integer between 0 and 32 (inclusive)\n* ``ACCOUNT_ID`` is an AWS numeric account ID\n\nFor port numbers, ``POSITIVE_INTEGER`` can be between 1 and 65535, and -1 means *all*.\n\n\nExample\n-------\n\nSuppose you have a sgmanager configuration file named \"myrules\" containing the following::\n\n    acct prd 11223344556677\n    \n    cidr prd-w1 10.208.0.0/16\n    \n    sg prd-w1-eop sg-12345678\n    sg prd-w1-app sg-abcdef12\n    \n    proto ssh tcp 22 22\n    \n    rule in prd-w1-eop prd-w1-app ssh\n    rule in prd-w1-eop prd-w1 ssh\n\nRunning ``sgmanager prd myrules`` would produce the following output::\n\n    in sg-12345678 sg-abcdef12 tcp 22 22\n    in sg-12345678 10.208.0.0/16 tcp 22 22\n\nUsing ``sgtables``\n******************\n\n.. hint::\n    See the output of ``sgtables --help`` for complete, current information\n    about available options.\n\n``sgtables`` has four functions: *list*, *add*, *remove*, and *update*\n\n``sgtables`` always requires an AWS profile (from ~/.aws/config), a region, and\na specific VPC to operate against (or the special name 'classic' for EC2\nClassic). ``sgtables`` only operates on one network at a time. EC2 classic is\nhandled as its own network/VPC.\n\nAll data-modification commands (everything except *list*) accept a ``--noop``\nargument (for no-op) that prevents any real changes from taking place. You can\nuse the ``--verbose`` flag to see more detail about the operations performed by\nthe command. ``--debug`` will also include low-level details.\n\nThe *add* command will try to add all rules passed to it (so long as the group\nexists in the VPC). Similarly, *remove* will try to remove all rules passed to\nit. You will be warned if the given rule already exists (for *add*) or if it is\nnot found (for *remove*), but this will not cause ``sgtables`` to fail.\n\n*update* behaves somewhat differently than the other two. Before making changes,\n*update* inspects the current ruleset and compares it to the input given. For\nany security group **mentioned as an owner in the rules list**, rules are added\nif needed, then rules are removed. To put it another way, *update* expects that\nthe rules passed to it are the **only** rules that should be in those groups.\n\n*Mentioned*, in this context, means that any rule not listed as an owner in the\nruleset will not be updated. ``sgtables`` can update all rules in all security\ngroups in a VPC if passed the ominuously-named ``--obliterate`` flag to\n*update*. When ``--obliterate`` is specified, ``sgtables`` assumes that the\nrules given to it are the **only** rules that should exist in the VPC. If a\ngroup exists but no rules are defined for it, that group will have all of its\nrules removed.\n\n%%%%%%%%%%%%%%%%%%\nInstalling sgtools\n%%%%%%%%%%%%%%%%%%\n\nsgtools is available in PyPI and is installable via pip::\n\n    pip install sgtools\n\nYou may also install sgtools from source, perhaps from the GitHub repo::\n\n    git clone https://github.com/RetailMeNot/sgtools.git\n    cd sgtools\n    python setup.py install\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretailmenotsandbox%2Fsgtools","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fretailmenotsandbox%2Fsgtools","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fretailmenotsandbox%2Fsgtools/lists"}