{"id":19907391,"url":"https://github.com/arsulegai/state-checker","last_synced_at":"2025-03-01T08:13:09.126Z","repository":{"id":72665075,"uuid":"197355662","full_name":"arsulegai/state-checker","owner":"arsulegai","description":"A lightweight and easy to use tool which accepts a log file, state descriptor, state machine files and identify corruptions by inspecting log files.","archived":false,"fork":false,"pushed_at":"2019-10-11T03:16:20.000Z","size":42,"stargazers_count":3,"open_issues_count":1,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-11T22:14:07.616Z","etag":null,"topics":["analysis","go","golang","state-machine","tool"],"latest_commit_sha":null,"homepage":"https://arsulegai.github.io/state-checker/","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/arsulegai.png","metadata":{"files":{"readme":"README.md","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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-07-17T09:12:38.000Z","updated_at":"2024-07-29T17:18:59.000Z","dependencies_parsed_at":"2023-03-11T13:54:57.537Z","dependency_job_id":null,"html_url":"https://github.com/arsulegai/state-checker","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/arsulegai%2Fstate-checker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsulegai%2Fstate-checker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsulegai%2Fstate-checker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/arsulegai%2Fstate-checker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/arsulegai","download_url":"https://codeload.github.com/arsulegai/state-checker/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241335591,"owners_count":19946085,"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":["analysis","go","golang","state-machine","tool"],"created_at":"2024-11-12T20:40:35.591Z","updated_at":"2025-03-01T08:13:09.091Z","avatar_url":"https://github.com/arsulegai.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# State Machine Analysis Tool\nThis is a tool which analyzes possible state transitions in a given input log.\nIf the log traces differ from what the actual trace states, it will raise a\nred flag.\n\nThe tool accepts three files as input `State Descriptor`, `State Machine` and\na `Log File`. The document further assumes the name of the descriptor file\nto be `state-descriptor.file`, name of the state machine file to be\n`state-machine.file` and the name of the log file to be `log.file`.\n\nThe tool use cases can be plenty, with the advancement in the tool there's\nno limit to what one can do. However these can be widely used for following,\n(Example output of these are given later in the document)\n\n* Use Case 1: Catch the abnormality in state transition of the application,\nwith the ability to match log traces using regular expression (Go's `regexp`\nis accepted).\n* Use Case 2: Catch the abnormality in state transition for particular value.\nThis is helpful where the application makes state transitions for multiple\nvalues simultaneously. For example, a web server serving request to multiple\nclients at the same time using different session ids. The tool can be used\nto identify if all the requests are handled gracefully as expected.\n\n# Sample Configuration\n\nThe `state-descriptor.file` file looks like following\n\n```\nState1| Log Trace To Be Searched Which Corresponds to State 1, has a pattern [a-z0-9]+\nState2| Log Trace To Be Searched Which Corresponds to State 2, has no pattern\nState3| Log Trace To Be Searched Which Corresponds to State 3, has a pattern [a-z][0-9][A-Z]+\n```\nThe `|` acts as `OR` operation. The line has to be read as `State1` or\n`Log Trace To Be Searched Which Corresponds to State 1, has a pattern [a-z0-9]+`\nboth of them are considered equivalent. Henceforth the log trace will be referred\nto using the state short-name in the `state-machine.file`.\n\n**Note:** The descriptor can be a `Golang` [regexp](https://godoc.org/regexp)\nexpression. If regex is used, a log trace matching regex will be considered\nas a state. Example is as follows\n\n```\nState1| Log Trace Pattern To Be Searched For \u003cValue\u003eVALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE\u003c/Value\u003e\nState2| Another Trace Pattern For \u003cValue\u003eVALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE\u003c/Value\u003e\nState3| Yet Another Trace Pattern For \u003cValue\u003eVALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE\u003c/Value\u003e\n\u003cValue\u003eVALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE\u003c/Value\u003e| has a pattern [XYZ]\n```\nIn this file, `\u003cValue\u003e` and `\u003c/Value\u003e` are special tags. The log patterns matching\n`VALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE`'s defined pattern is identified.\nThis transition happens for each of the value matching\n`VALUE-TO-BE-FOUND-FOR-TRANSITION-OF-STATE`, red flag is raised if any of the\nvalue does not transition as expected.\n\n**Note:** Different values can be overlapping in the log file. That is,\nthere can be multiple values performing state transition at the same time.\nTool handles them all.\n\nThe `state-machine.file` file looks like following\n\n```\nState1|State2\nState2|State3,State1\nState3|State1\n```\n\nIn the above example, there's possible transition from State2 to State3 or\nState1. The precedence of transition is that State2 will first try to move to\nState3 before moving to State1. But it should always go from State1 to State2\nor State3 to State1.\n\nA special `END_STATE` can be used to stop the state transition abruptly. It's\nhelpful in positive manner for the `Use Case 2` which is descrived initially.\nExample usage is discussed later in the document.\n\nThe `log.file` file can be any text file, example\n\n```\n[Log Trace Level, Time Information] Log Trace To Be Searched Which Corresponds to State 1, has a pattern ab1234\n[Log Trace Level, Time Information] Some Other Log Trace 1\n[Log Trace Level, Time Information] Some Other Log Trace 2\n[Log Trace Level, Time Information] Log Trace To Be Searched Which Corresponds to State 2, has no pattern\n[Log Trace Level, Time Information] Some Other Log Trace 3\n[Log Trace Level, Time Information] Some Other Log Trace 4\n[Log Trace Level, Time Information] Some Other Log Trace 5\n[Log Trace Level, Time Information] Some Other Log Trace 6\n[Log Trace Level, Time Information] Log Trace To Be Searched Which Corresponds to State 3, has a pattern a1A\n```\n\nIn the above example, there's no error in parsing the file.\n\nThe tool works as follows\n1. Reads the input log file line by line\n2. If any of the log line matches a state as per the descriptor file, it's\nconsidered as a start of state-machine analysis.\n3. If a log trace matches a state from descriptor file and transitions to\nunexpected state (not as per the state-machine file), a red flag is raised.\n\n**Note:** The state machine has no start or end. Because log file can be\nsharded and the state machine can repeat itself in a loop. The way it works\nis identifying first state in the log.\n\n# Example Output\n\n## Use Case 1: (Simple state transition with pattern matching)\n`state-machine.file` is as follows\n\n```\nConsensusNewMessage|ConsensusBlockValid\nConsensusBlockValid|StartCommitting,IgnoreBlock\nStartCommitting|ConsensusBlockCommit\nIgnoreBlock|ConsensusNewMessage\nConsensusBlockCommit|ConsensusNewMessage\n```\n\n`state-descriptor.file` is as follows\n```\nConsensusNewMessage| Received message: CONSENSUS_NOTIFY_BLOCK_NEW\nConsensusBlockValid| Received message: CONSENSUS_NOTIFY_BLOCK_VALID\nConsensusBlockCommit| Received message: CONSENSUS_NOTIFY_BLOCK_COMMIT\nStartCommitting| Committing [a-z0-9]+\nIgnoreBlock| Ignoring [a-z0-9]+\n```\n\n`log.file` is a sample debug log file from\n[Hyperledger Sawtooth PoET](https://github.com/hyperledger/sawtooth-poet)\napplication.\nOutput from the tool when run with the sample log file which has error is as follows\n\n```\nState Machine Checker, Version: 0.1\nThe application utilizes [State Machine File (-state) State Description File (-descriptor) Log File (-log)]\n2019/07/26 21:55:07 Now parsing the log file\n2019/07/26 21:55:07 [03:25:00.506 [MainThread] engine DEBUG] Received message: CONSENSUS_NOTIFY_BLOCK_NEW transitioned state from {StartCommitting } to {ConsensusNewMessage }\n2019/07/26 21:55:07 Cannot transition from {StartCommitting } to {ConsensusNewMessage }\nPossible are [{ConsensusBlockCommit }]\n\n2019/07/26 21:55:07 [03:25:00.506 [MainThread] engine DEBUG] Received message: CONSENSUS_NOTIFY_BLOCK_NEW\nPlease refer to this found line for debugging\n```\n\n## Use Case 2: (Value based state transition)\n`state-machine.file` is as follows\n\n```\nConsensusBlockValid|CommitBlock,IgnoreBlock\nCommitBlock|END_STATE\nIgnoreBlock|END_STATE\nEND_STATE|ConsensusBlockValid\n```\n\n`state-descriptor.file` is as follows\n\n```\nConsensusBlockValid| Passed consensus check: \u003cValue\u003eBLOCK_HERE\u003c/Value\u003e\nCommitBlock| Committing \u003cValue\u003eBLOCK_HERE\u003c/Value\u003e\nIgnoreBlock| Ignoring \u003cValue\u003eBLOCK_HERE\u003c/Value\u003e\n\u003cValue\u003eBLOCK_HERE\u003c/Value\u003e| [a-z0-9]+\n```\n\n`log.file` is again a sample debug log file from\n[Hyperledger Sawtooth PoET](https://github.com/hyperledger/sawtooth-poet)\napplication.\nOutput from the tool when run with the sample log file which has error is as follows\n\n```\nState Machine Checker, Version: 0.1\nThe application utilizes [State Machine File (-state) State Description File (-descriptor) Log File (-log)]\n2019/07/26 22:03:10 Now parsing the log file\n2019/07/26 22:03:10 [03:31:10.852 [MainThread] engine INFO] Passed consensus check: bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6 transitioned state from {ConsensusBlockValid bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6} to {ConsensusBlockValid bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6}\n2019/07/26 22:03:10 Cannot transition from {ConsensusBlockValid bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6} to {ConsensusBlockValid bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6}\nPossible are [{CommitBlock } {IgnoreBlock }]\n\n2019/07/26 22:03:10 [03:31:10.852 [MainThread] engine INFO] Passed consensus check: bb3e98cfd3de79fce125a62d76a6cce788b8ea1357b0400a79295cd4e5d10cbf2f429fdc4cf03c9859f4e231243f82796f46f44934cf8a3c8556d0bfa821b6f6\nPlease refer to this found line for debugging\n```\n\n# Build and Run\nThe program is tested on Ubuntu 18.04 LTS (Bionic). Also the docker build\noptions provided generates a binary to execute on the bionic machine.\n\n## Bare Metal Build\nRefer to [Golang/Go Repository](https://github.com/golang/go) to know how to\nconfigure Go in your machine. To build the binary of the standalone application\nrun the following command from within `src/app` directory. Also set project\nroot directory in `$GOPATH`.\n\n```\ngo build\n```\n\n## Docker Build\n**Note:**\nTested on\n1. Docker-compose version 1.22\n2. Docker version 18.06-ce\n\nTo generate a binary, run the docker-compose file from within the root\ndirectory of the repository (example, where you clone the git repository)\n\n```\ndocker-compose -f docker/compose/build.yaml up\n```\nIt will mount the local directory to the container and create a `bin` directory\nwhere you'll find the executable binary.\n\n**Note:**\n- If the build is successful, docker-compose up should exit with\nstatus code 0.\n- For generating a binary for the Mac. Please use the file `docker/compose/mac-build.yaml`.\n\n## Run\nTo run the application use following command format, assumes that generated\nbinary is in the `$PATH`. If you are using the docker compose file for generation\nthen add `\u003cfull-path-to-repository-root-folder\u003e/bin` in `$PATH`.\n\n```\nstate-machine-analyzer -descriptor state-descriptor.file -state state-machine.file -log log.file\n```\n\n## Help\n\n```\nstate-machine-analyzer --help\n```\n\n```\nState Machine Checker, Version: 0.1\nThe application utilizes [State Machine File (-state) State Description File (-descriptor) Log File (-log)]\nUsage of state-machine-analyzer:\n  -descriptor string\n        State description file (default \"state.descriptor\")\n  -log string\n        Log file to parse. (default \"file.log\")\n  -state string\n        State machine file. (default \"state.machine\")\n  -v    Print the version number.\n```\n\n## Machine in proxy network\nIf you're using the tool on a machine in a proxy network environment, the build\nmay fail to get required packages or may fail during the docker image creation.\nPlease create a file `config.json` with following contents and place it under\nthe `/home/$USER/.docker/` directory. Create the directory if not present\nalready. The file looks like the following\n\n```\n{\n \"proxies\":\n {\n   \"default\":\n   {\n     \"httpProxy\": \"http://proxy-address-here:\u003cproxy-port-http\u003e\",\n     \"httpsProxy\": \"http://proxy-address-here:\u003cproxy-port-https\u003e\",\n     \"noProxy\": \"127.0.0.1,localhost\",\n     \"hkpProxy\": \"http://proxy-address-here:\u003cproxy-port-hkp\u003e\"\n   }\n }\n}\n```\n\n# Developers\n\n## Contributions\nYou're free to improvise the application, raise a pull request to the original\nrepository after your implementation. Each commit must include `Signed-off-by:`\nin the commit message (run `git commit -s` to auto-sign). This sign off means\nyou agree the commit satisfies the [Developer Certificate of\nOrigin(DCO)](https://developercertificate.org/).\n\n## Beautiful Go\nFor the benefit of new code gazers, run the `go fmt` before raising the pull\nrequest to the [https://github.com/arsulegai/state-checker](GitHub). There's\na docker compose file for help as well. Run the command from root directory\nof the repository.\n\n```\ndocker-compose -f docker/compose/fmt.yaml up\n```\n**Note:** Command will exit with the code 0 upon success.\n\n## License\nThis software is licensed under the [Apache License Version 2.0](LICENSE)\nsoftware license.\n\n\u0026copy; Copyright 2019, Intel Corporation\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farsulegai%2Fstate-checker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farsulegai%2Fstate-checker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farsulegai%2Fstate-checker/lists"}