{"id":27953803,"url":"https://github.com/binaryanalysisplatform/bap-veri","last_synced_at":"2025-05-07T17:14:57.512Z","repository":{"id":43038460,"uuid":"53398713","full_name":"BinaryAnalysisPlatform/bap-veri","owner":"BinaryAnalysisPlatform","description":"bil verification tool","archived":false,"fork":false,"pushed_at":"2022-06-30T19:09:37.000Z","size":111,"stargazers_count":12,"open_issues_count":0,"forks_count":4,"subscribers_count":5,"default_branch":"master","last_synced_at":"2025-05-07T17:14:49.607Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"OCaml","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/BinaryAnalysisPlatform.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":"2016-03-08T09:15:24.000Z","updated_at":"2024-07-26T12:17:08.000Z","dependencies_parsed_at":"2022-09-06T06:11:08.671Z","dependency_job_id":null,"html_url":"https://github.com/BinaryAnalysisPlatform/bap-veri","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryAnalysisPlatform%2Fbap-veri","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryAnalysisPlatform%2Fbap-veri/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryAnalysisPlatform%2Fbap-veri/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/BinaryAnalysisPlatform%2Fbap-veri/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/BinaryAnalysisPlatform","download_url":"https://codeload.github.com/BinaryAnalysisPlatform/bap-veri/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":252922320,"owners_count":21825639,"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":"2025-05-07T17:14:56.745Z","updated_at":"2025-05-07T17:14:57.500Z","avatar_url":"https://github.com/BinaryAnalysisPlatform.png","language":"OCaml","funding_links":[],"categories":[],"sub_categories":[],"readme":"# BAP Lifter Accuracy Verification Tool\n\nThis tool uses trace files from [pintrace] or [qemu] to verify the lifters accuracy. For each instruction, the tracing tool records in the trace file all side effects, such as memory accesses, register updates, and so on. We call these effects the [trace events][trace-events]. The bap-veri tool reads the events from the trace file then disassembles and lifts each instruction (which is also stored in the trace file) and emulates them using a BIL interpreter that collects all side-effects in the form of a set of trace events. Ideally, the stored set and the emulated sets should coincide. In reality, the tracing tools have their own abstractions and could be less precise or more precise than BAP. For example, qemu doesn't really track changes in the status registers and instead generates a flag change event even if it wasn't changed. To address this, bap-veri uses [policy](#policy) files that contain simple rules describing which events shall be ignored and which events are crucial. \n\nEach instruction is compared independently starting from a clean state. Since BAP doesn't have access to the full image and execution enviroment, like the state of the heap or registers, we peek the values from the trace, e.g., if in the trace we see event like `RAX =\u003e 0x2A` we know that `RAX` contained `0x2A`. \n\n\n## Installing\n\nTo install the tool use opam, e.g.,\n\n```\nopam install bap-veri\n```\n\nIf you need the latest master version, do\n```\nopam pin add --dev-repo bap-veri\n```\n\n\n## Running \n\nFirst of all, you will need to obtain a trace file. For that you need to build either of our tracing tools, [pin-trace] or [qemu]. Both tracing tools store their information using the [bap-frames] file format, so you need to build and install the [bap-frames] codec as well. If you installed bap from opam, e.g., with `opam install bap`, then you can just do \n```\nopam install bap-frames\n```\n\nAlternatively, you can build it from sources, see the [coreponding instructions](https://github.com/BinaryAnalysisPlatform/bap-frames#from-sources).\n\nOnce you have everything ready, you can run `bap veri` as\n\n```\nbap veri --show-errors --show-stat \u003ctrace-file\u003e\n```\n\nNotice that there's no need for the original binary or libraries, all the necessary information is stored in the binary. Before running `bap veri` you can use `bap --trace-dump \u003ctrace-file\u003e` to print the contents of the trace file in a human-readable format.\n\nYou can also specify a policy file using `--rules \u003cpolicy-file\u003e`. If you don't know what it is, read the next section. \n\n## Policy\n\nThe policy file contains a list of rules, somewhat similar to the firewall rules. The rules are executed in order, the first that matches is applied. A rule contains four fields: `ACTION INSN TRACER_EVENT LIFTER_EVENT`:\n\n1. The `ACTION` field is either `SKIP` or `DENY`. `DENY` means that we found an unacceptable inconsistency that should be reported as a problem. The `SKIP` action means that we can ignore this inconsistency.\n2. The `INSN` field could contain an instruction name like `MOV64rr` or regular expression, like `MOV.*`, the rule will be applied only to instructions that match the INSN field.\n3. The `TRACER_EVENT` field denotes a [tracing event][trace-events] generated by the tracing tool. It could be a string or a regular expression, or `''` that denotes a lack of event. The rule will be applied the tracer generated a matching event. \n4. The `LIFTER_EVENT` field denotes a [tracing event][trace-events] generated during the emulation of a lifted instruction. It has the same format as the `TRACER_EVENT`.\n\n\nWhen bap-veri detects that the set of tracer events is not equal to the set of lifter events it will use the specified policy file to figure out what to do next. For each event in either set complements it will try to find the matching rule. Matching is performed on the textual representation of events (you can always use `bap --trace-dump \u003ctrace-file\u003e` to see how they look). Rules are written in a text file in which every line is either a rule, a comment, or an empty line. A comment line starts with `#` and is ignored. The rule must have exactly four fields separated with whitespaces. If the field contains a space it should be delimited with with single or double quotes, e.g.,  `\"RAX =\u003e .*\"`. If a field is empty (i.e., matches with an empty string or an absence of event), then use `''` or `\"\"`. \n\n### Examples\n\nLet's imagine that a tracer, unlike BAP, ignores accesses to the `ZF` register. To skip this inconsistency, we write the following rule\n```\nSKIP .* '' 'ZF -\u003e .*'\n```\n\nIt literally means, for any instruction, if there is an umatched read from `ZF` then skip it.\n\nThe next two rules specify that tracer and lifter event sets must be equal. And this is the default policy, when no policy is specified. \n```\nDENY .* .* ''\nDENY .* '' .*\n```\n\nThe rules match with every instruction and trigger whenever there is a `TRACER_EVENT` that doesn't has a matching `LIFTER_EVENT` (the first rule) or there is a `LIFTER_EVENT` that doesn't have a matching `LIFTER_EVENT.\n\n\n### Backreferences\n\nIt is also possible to use back references in regular expressions. A group is denoted with simple parentheses, e.g., and could be referenced by number (counting from 1) using `\\\u003cn\u003e` syntax, e.g.,\n\n```\nDENY .* '(.F) \u003c= .*' '\\1 \u003c= .*'\n```\n\nThis rule captures any writes to a flag register, e.g., `ZF`, `PF`, etc, that write different values, e.g., it will match with, `ZF \u003c= 0` vs. `ZF \u003c= 1`. Keep in mind that rules are only applied to unmatched event, so if the events were already matching then they will not be even checked by the policy checker. \n\n# Developing\n\nIf you want to modify the tool, then make sure that [bap][bap] is [installed][bap-install]. Note, that installing bap prebuilt binaries will not work. You need libraries and the toolchain. Also, make sure that you have installed other dependencies. You can look them in the [opam](./opam) file, or ask opam to do the work for you using `opam pin`, e.g., \n\n```\nopam pin add bap-veri --dev-repo\nopam install bap-veri --deps-only\nopam pin remove bap-veri\n```\n\nNow, when all the prerequisites are met, we can build and install bap-veri,\n\n```\noasis setup\nmake\nmake install\n```\n\nNow you can change the code and repeat the last two steps. \n\n[trace-events]: https://binaryanalysisplatform.github.io/bap/api/master/bap-traces/Bap_traces/Std/index.html#trace-events\n[pintrace]: https://github.com/BinaryAnalysisPlatform/bap-pintraces\n[qemu]: https://github.com/BinaryAnalysisPlatform/qemu\n[bap]: https://github.com/BinaryAnalysisPlatform/bap\n[bap-install]: https://github.com/BinaryAnalysisPlatform/bap#from-sources\n[bap-frames]: https://github.com/BinaryAnalysisPlatform/bap-frames\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryanalysisplatform%2Fbap-veri","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbinaryanalysisplatform%2Fbap-veri","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbinaryanalysisplatform%2Fbap-veri/lists"}