{"id":17051866,"url":"https://github.com/ancat/equation","last_synced_at":"2025-10-05T15:07:08.489Z","repository":{"id":57747233,"uuid":"522393033","full_name":"ancat/equation","owner":"ancat","description":"Equation exposes a minimal environment to allow safe execution of Ruby code represented via a custom expression language.","archived":false,"fork":false,"pushed_at":"2023-02-12T06:26:35.000Z","size":48,"stargazers_count":9,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-21T00:37:16.383Z","etag":null,"topics":["expression-language","ruby","security"],"latest_commit_sha":null,"homepage":"https://rubygems.org/gems/equation","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ancat.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-08T03:31:57.000Z","updated_at":"2025-01-15T17:57:22.000Z","dependencies_parsed_at":"2023-02-15T20:25:21.320Z","dependency_job_id":null,"html_url":"https://github.com/ancat/equation","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ancat%2Fequation","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ancat%2Fequation/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ancat%2Fequation/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ancat%2Fequation/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ancat","download_url":"https://codeload.github.com/ancat/equation/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248595301,"owners_count":21130501,"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":["expression-language","ruby","security"],"created_at":"2024-10-14T10:07:47.780Z","updated_at":"2025-10-05T15:07:03.470Z","avatar_url":"https://github.com/ancat.png","language":"Ruby","readme":"# Equation [WIP]\n\nA rules engine for your Ruby app! Use a constrained and relatively safe language to express logic for your Ruby app, without having to write Ruby. This allows you to use text (e.g. in a configuration file or database) to store logic in a way that can be updated independently from your code faster than it takes for a deploy without opening extra security vulnerabilities. \n\nUse cases include:\n\n* writing rules to describe HTTP traffic that then gets dropped, like a WAF\n* writing policies to express authorization logic\n* etc\n\nModeled loosely after [Symfony Expression Language](https://symfony.com/doc/current/components/expression_language.html).\n\n## Demos\n\nTake a look at the examples directory for some demonstrations of Equation's capabilities. The main example is a [web application firewall](https://github.com/ancat/equation/tree/main/examples/rails_waf) for Rails; rules can be managed from any ActiveStorage compatible backend (e.g. filesystem, Amazon AWS, etc) and updated independently of application code, allowing for faster and more expressive blocking logic without having to wait for a deploy to go through.\n\n## Example\n\nIn this example, we'll use a rule to determine whether a request should be dropped or not. While the rule here is hardcoded into the program, it could just as easily be pulled from a database, some redis cache, etc instead. Rules can also be cached, saving you an extra parsing step.\n\n```ruby\nrequire 'equation'\n\n# set up the execution environment and give it access to the rails request object\nengine = EquationEngine.new(default: {\n  age: 12,\n  username: \"OMAR\",\n  request: request\n})\n\nsuspicious_request = engine.eval(rule: '$request.path == \"/api/login\" \u0026\u0026 $request.remote_ip == \"1.2.3.4\" \u0026\u0026 $username == \"OMAR\"')\nif suspicious_request\n  # log some things, notify some people\nend\n```\n\n## Language Features\n\nBecause Equation is modeled after [Symfony Expression Language](https://symfony.com/doc/current/components/expression_language/syntax.html), it supports a lot of the same features. For a more exhaustive list, check out the [tests](https://github.com/ancat/equation/blob/main/spec/equation_spec.rb).\n\n### Literals\n\n* Strings: double quotes, e.g. `\"hello world\"`\n* Numbers: all treated as floats, e.g. `0`, `-10`, `0.5`\n* Arrays: square brackets, e.g. `[403, 404]` or `[\"yes\", \"no\", \"maybe\"]`; can be mixed types\n* Booleans: `true`, `false`\n* Null: `nil`\n\n### Variables\n\nVariables are only made available to the engine at initialization. For example, given this setup code:\n\n```ruby\nengine = EquationEngine.new(default: {name: \"OMAR\", age: 12})\n```\n\nThese variables and all their properties are accessible from within rules:\n\n```\n$name == \"OMAR\" # true\n$name.length    # 4\n$name.reverse   # RAMO\n```\n\n### Methods\n\nLike variables, methods are only made available to the engine at initialization. They can take any number and type of arguments, including variables or return values from other methods.\n\n```ruby\nengine = EquationEngine.new(default: {age: 12}, methods: {is_even: -\u003e(n) {n%2==0}})\n```\n\n`is_even` can now be called as follows:\n\n```\nis_even(5)    # false\nis_even($age) # true\n```\n\n### Comparisons\n\n```\n$name == \"Dumpling\" \u0026\u0026 $age \u003e= 12\n$name in [\"Dumpling\", \"Meatball\"] || $age == 12\n```\n\n## Development\n\n* To work on the expression language itself, take a look at `lib/equation_grammar.treetop`. Equation is built using [treetop](https://cjheath.github.io/treetop/).\n* Run `bundle exec rake build_grammar` to generate the corresponding parser Ruby code.\n* Run `bundle exec rake spec` to run tests.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fancat%2Fequation","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fancat%2Fequation","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fancat%2Fequation/lists"}